Skill: secondport/sure-finance-skill (version 0.0.7)

--- name: sure-finance-skill description: "Sure Finance API skill. Use when the user wants personal finance insights, account and transaction operations, tags/categories management, imports, or chat workflows in Sure." license: "MIT" metadata: {"openclaw":{"emoji":"📈","primaryCredential":"SURE_API_KEY","requires":{"bins":["curl"],"env":["SURE_API_KEY","SURE_BASE_URL"]}},"clawdbot":{"emoji":"📈","primaryCredential":"SURE_API_KEY","requires":{"bin":["curl"],"env":["SURE_API_KEY","SURE_BASE_URL"]}}} --- # Sure Finance Skill This skill provides a reliable workflow to interact with Sure's API. ## Scope Use this skill for: - Listing and analyzing accounts, categories, tags, imports, chats, and transactions. - Creating and updating transactions, tags, chats, and imports. - Building financial summaries from Sure data. - Helping users connect self-hosted Sure environments (Docker, compose, external assistant) with API usage. Do not use this skill for: - Guessing undocumented endpoints or request shapes. - Running destructive operations without explicit user confirmation. - Fabricating financial figures when the API is unavailable. ## Compatibility Contract Follow these rules strictly to maximize compatibility: - The skill is instruction-only. Core runtime actions are limited to `curl` requests against `$SURE_BASE_URL` using `X-Api-Key`. - Optional self-hosting and external-assistant flows (documented in `docs/`) may reference additional URLs and env vars. These flows run only when the user explicitly requests them and never during normal API usage. - Always use plain Markdown. Do not include HTML entities like `&nbsp;`. - Keep shell commands copy-paste ready. - Use only ASCII in examples unless API data requires otherwise. - Do not require tools beyond `curl` for core operations. - Read credentials only from environment variables. - Never print API keys or tokens in output. - Do not instruct reading unrelated local files, keychains, or secret stores. - If `SURE_BASE_URL` has no scheme, normalize to `http://` before use. - For all list endpoints, support pagination via `page` and `per_page`. - Provide short, deterministic outputs when users request automation-friendly responses. ## Environment Setup Required variables: ```bash export SURE_API_KEY="YOUR_API_KEY" export SURE_BASE_URL="https://app.sure.am" ``` Optional sensitive variables used only for specific self-hosted or external-assistant scenarios: ```bash # External assistant validation (optional) export MCP_API_TOKEN="..." export MCP_USER_EMAIL="[REDACTED_SECRET]" export EXTERNAL_ASSISTANT_URL="https://your-agent/v1/chat/completions" export EXTERNAL_ASSISTANT_TOKEN="..." # Self-hosting bootstrap (optional) export SECRET_KEY_BASE="..." export POSTGRES_PASSWORD="..." ``` These optional variables are intentionally not listed in `metadata.clawdbot.requires.env` because the core skill runtime does not require them. Do not request or provide these optional secrets for normal API usage. Use them only when the user explicitly asks to run self-hosting or external-assistant validation flows. Validation check: ```bash curl --silent --show-error --fail \ --request GET \ --url "$SURE_BASE_URL/api/v1/accounts?page=1&per_page=1" \ --header "X-[REDACTED_SECRET]" ``` If this fails: - Verify the base URL and API key. - Confirm Sure server is running and reachable. - If self-hosted with Docker, verify containers are healthy. ## Authentication All requests must include: ```bash --header "X-[REDACTED_SECRET]" ``` ## Core API Quick Reference ### Accounts List accounts: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/accounts?page=1&per_page=25" \ --header "X-[REDACTED_SECRET]" ``` ### Categories List categories: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/categories" \ --header "X-[REDACTED_SECRET]" ``` Retrieve category: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/categories/{id}" \ --header "X-[REDACTED_SECRET]" ``` ### Chats List chats: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/chats" \ --header "X-[REDACTED_SECRET]" ``` Create chat: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/chats" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "title": "Monthly budget review", "message": "Summarize my spending trends.", "model": "default" }' ``` Retrieve chat: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/chats/{id}" \ --header "X-[REDACTED_SECRET]" ``` Update chat: ```bash curl --request PATCH \ --url "$SURE_BASE_URL/api/v1/chats/{id}" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "title": "Updated chat title" }' ``` Delete chat: ```bash curl --request DELETE \ --url "$SURE_BASE_URL/api/v1/chats/{id}" \ --header "X-[REDACTED_SECRET]" ``` Create chat message: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/chats/{chat_id}/messages" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "content": "What changed this month vs last month?", "model": "default" }' ``` Retry last assistant response: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/chats/{chat_id}/messages/retry" \ --header "X-[REDACTED_SECRET]" ``` ### Imports List imports: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/imports" \ --header "X-[REDACTED_SECRET]" ``` Create import: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/imports" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "raw_file_content": "date,amount,name\n2026-01-01,25.00,Coffee", "type": "TransactionImport", "account_id": "<account_id>", "publish": "true", "date_col_label": "date", "amount_col_label": "amount", "name_col_label": "name", "category_col_label": "category", "tags_col_label": "tags", "notes_col_label": "notes", "date_format": "YYYY-MM-DD", "number_format": "1,234.56", "signage_convention": "inflows_positive", "col_sep": "," }' ``` Retrieve import: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/imports/{id}" \ --header "X-[REDACTED_SECRET]" ``` ### Tags List tags: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/tags" \ --header "X-[REDACTED_SECRET]" ``` Create tag: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/tags" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "tag": { "name": "Travel", "color": "#3B82F6" } }' ``` Retrieve tag: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/tags/{id}" \ --header "X-[REDACTED_SECRET]" ``` Update tag: ```bash curl --request PATCH \ --url "$SURE_BASE_URL/api/v1/tags/{id}" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "tag": { "name": "Travel Updated", "color": "#2563EB" } }' ``` Delete tag: ```bash curl --request DELETE \ --url "$SURE_BASE_URL/api/v1/tags/{id}" \ --header "X-[REDACTED_SECRET]" ``` ### Transactions List transactions: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/transactions?page=1&per_page=25" \ --header "X-[REDACTED_SECRET]" ``` Create transaction: ```bash curl --request POST \ --url "$SURE_BASE_URL/api/v1/transactions" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "transaction": { "account_id": "<account_id>", "date": "2026-03-01", "amount": 123.45, "name": "Groceries", "description": "Weekly grocery shopping", "notes": "", "currency": "USD", "category_id": "<category_id>", "merchant_id": "<merchant_id>", "nature": "expense", "tag_ids": ["<tag_id>"] } }' ``` Retrieve transaction: ```bash curl --request GET \ --url "$SURE_BASE_URL/api/v1/transactions/{id}" \ --header "X-[REDACTED_SECRET]" ``` Update transaction: ```bash curl --request PATCH \ --url "$SURE_BASE_URL/api/v1/transactions/{id}" \ --header "Content-Type: application/json" \ --header "X-[REDACTED_SECRET]" \ --data '{ "transaction": { "name": "Groceries - updated", "amount": 130.00, "notes": "adjusted amount" } }' ``` Delete transaction: ```bash curl --request DELETE \ --url "$SURE_BASE_URL/api/v1/transactions/{id}" \ --header "X-[REDACTED_SECRET]" ``` ## Recommended Agent Workflow When asked to perform analytics: 1. List accounts and transactions with pagination. 2. Aggregate monthly totals by category and account. 3. Validate suspicious outliers against raw transactions. 4. Return clear assumptions and confidence level. When asked to mutate data: 1. Confirm target resource ID and intended change. 2. Execute create or update call. 3. Re-fetch the resource to verify success. 4. Summarize fields changed. ## Self-Hosted Sure Notes > **Scope note:** The commands below fetch compose files from the Sure project repository on GitHub. Review any downloaded file before running `docker compose up`. These flows are optional and only relevant when the user explicitly requests self-hosting setup. For Docker-based self-hosting: - Official image tags include `latest` and `stable`. - Default local URL is `http://localhost:3000`. - API key is generated in Sure account settings. For AI and external assistant mode: - Sure supports external assistant integration. - Pipelock can proxy and inspect AI and MCP traffic. - In AI compose mode, external agents should target the Pipelock reverse proxy when applicable. ## Error Handling For HTTP 401 or 403: - Verify `SURE_API_KEY`. - Confirm the key belongs to the active Sure user. For HTTP 404: - Verify resource ID and base URL. For HTTP 422: - Validate JSON payload shape and enum values. For network errors: - Confirm host reachability. - If self-hosted, verify `docker compose ps` status. ## Data Safety - Treat all finance data as sensitive. - Do not expose full account numbers or secrets in logs. - Prefer redacting personally identifiable information in shared outputs. ## Additional Files Use the supporting files in this skill package: - `docs/openclaw-compatibility.md` - `docs/api-playbooks.md` - `docs/self-hosting-quickstart.md`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)