Sure API

Use this skill when the user asks to:

• operate Sure through its API
• inspect accounts, transactions, categories, tags, merchants, imports, holdings, trades, valuations, or chats
• create/update/delete supported Sure resources safely
• verify whether the upstream Sure API changed
• keep this skill in sync with the official Sure API docs

Official source-of-truth URLs

These are the URLs the agent should trust first when updating or validating this skill:

• Sure repo:

  https://github.com/we-promise/sure

• API docs directory:

  https://github.com/we-promise/sure/tree/main/docs/api

• OpenAPI spec page:

  https://github.com/we-promise/sure/blob/main/docs/api/openapi.yaml

• Raw OpenAPI download used by the update script:

  https://raw.githubusercontent.com/we-promise/sure/main/docs/api/openapi.yaml

If behavior and local scripts disagree, re-check the upstream OpenAPI first.

Local config

Read secrets from secure env only:

• SURE_BASE_URL

• SURE_API_KEY

Single source of truth:

secure/api-fillin.env

Never paste the API key into chat or into non-secure files.

Auth

Default auth header:

• X-Api-Key: <SURE_API_KEY>

Note: the current upstream OpenAPI snapshot also shows

Authorization

header notes on some valuation endpoints. Treat upstream OpenAPI as authoritative if those endpoints behave differently in practice.

Skill layout

skills/sure-api/
├── SKILL.md
├── references/
│   ├── openapi.yaml
│   └── api_endpoints_summary.md
└── scripts/
    ├── sure_api_request.sh
    ├── sure_api_smoke.sh
    ├── sure_api_cli.js
    ├── sure_openapi_update.sh
    ├── sure_openapi_summarize.js
    └── sure_api_acceptance.sh

Capability model

This skill has two layers:

Layer 1: high-level wrapped commands

Use these first for common operations.

Implemented in

scripts/sure_api_cli.js

:

• accounts:list

• categories:list

• tags:list

• tags:create

• tags:update

• tags:delete

• merchants:list

• transactions:list

• transactions:get

• transactions:create

• transactions:update

• transactions:delete

• imports:list

• holdings:list

• trades:list

Layer 2: raw official endpoint access

For any official endpoint not yet wrapped by the high-level CLI, use:

• bash skills/sure-api/scripts/sure_api_request.sh <METHOD> <PATH> [curl args...]

This means the skill can still operate against official endpoints such as:

• merchant detail
• holding detail
• import detail / create import
• trade create / retrieve / update / delete
• valuation create / retrieve / update
• chats list / create / retrieve / update / delete / send message / retry
• other official endpoints present in

  references/openapi.yaml

Quick start

Smoke test

bash skills/sure-api/scripts/sure_api_smoke.sh

Common wrapped commands

node skills/sure-api/scripts/sure_api_cli.js accounts:list
node skills/sure-api/scripts/sure_api_cli.js categories:list --classification expense
node skills/sure-api/scripts/sure_api_cli.js tags:list
node skills/sure-api/scripts/sure_api_cli.js merchants:list
node skills/sure-api/scripts/sure_api_cli.js transactions:list --start_date 2026-03-01 --end_date 2026-03-31 --type expense
node skills/sure-api/scripts/sure_api_cli.js holdings:list --account_id <uuid>
node skills/sure-api/scripts/sure_api_cli.js trades:list --account_id <uuid> --start_date 2026-03-01 --end_date 2026-03-31

Safe write pattern

Always prefer:

1. read current state
2. dry-run if the wrapped command supports it
3. send the real write only with explicit confirmation flags

Example:

node skills/sure-api/scripts/sure_api_cli.js transactions:create \
  --account_id <uuid> \
  --date 2026-03-01 \
  --amount 12.34 \
  --name "午饭" \
  --nature expense \
  --dry-run

node skills/sure-api/scripts/sure_api_cli.js transactions:create \
  --account_id <uuid> \
  --date 2026-03-01 \
  --amount 12.34 \
  --name "午饭" \
  --nature expense \
  --yes

Raw endpoint examples for official API coverage

Retrieve a merchant by id

bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/merchants/<merchant-id>

Retrieve a holding by id

bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/holdings/<holding-id>

Retrieve an import by id

bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/imports/<import-id>

Create an import from raw CSV content

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/imports \
  -H 'Content-Type: application/json' \
  -d '{
    "raw_file_content": "date,amount,name\n2026-03-01,12.34,午饭",
    "type": "TransactionImport",
    "account_id": "<account-uuid>",
    "publish": "true"
  }'

Create a trade

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/trades \
  -H 'Content-Type: application/json' \
  -d '{
    "trade": {
      "account_id": "<account-uuid>",
      "date": "2026-03-01",
      "qty": 10,
      "price": 12.5,
      "type": "buy",
      "ticker": "AAPL"
    }
  }'

Create a valuation

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/valuations \
  -H 'Content-Type: application/json' \
  -d '{
    "valuation": {
      "account_id": "<account-uuid>",
      "amount": 10000,
      "date": "2026-03-01",
      "notes": "Month-end valuation"
    }
  }'

Create a chat and send a message

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/chats \
  -H 'Content-Type: application/json' \
  -d '{"title":"Monthly review","message":"Summarize March spending"}'

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/chats/<chat-id>/messages \
  -H 'Content-Type: application/json' \
  -d '{"content":"Show biggest merchant changes"}'

Pagination and filtering

Most list endpoints return a resource list plus a pagination block. Typical filters in the official API include:

• page

• per_page

• account/category/merchant/tag ids
• date or date ranges
• type/status filters on some resources

For exact parameters, read

references/openapi.yaml

.

Error handling

• 401

  /

  403

  → auth missing, invalid, or insufficient feature scope

• 404

  → wrong path or object not found

• 422

  → validation error; inspect request body against

  references/openapi.yaml

• 429

  /

  5xx

  → retry with backoff up to 3 times if the action is idempotent

Self-update this skill

This skill is designed to be self-maintainable.

Fast refresh from official API

bash skills/sure-api/scripts/sure_openapi_update.sh

What it does:

1. downloads the latest official OpenAPI from the Sure GitHub repo
2. overwrites

   references/openapi.yaml

3. regenerates

   references/api_endpoints_summary.md

After updating OpenAPI

Do this in order:

1. re-read

   references/api_endpoints_summary.md

2. compare new endpoints/params with current

   sure_api_cli.js

3. extend high-level wrappers only for endpoints that are common, stable, and worth scripting
4. keep less-common endpoints accessible via

   sure_api_request.sh

5. run acceptance checks

When to read references

Read

references/openapi.yaml

when you need:

• exact request bodies
• exact response shapes
• enum values
• parameter names
• authoritative behavior after upstream changes

Read

references/api_endpoints_summary.md

when you need:

• a fast endpoint inventory
• a quick check of what the upstream API currently exposes

ClawHub publish readiness

Before publishing or bumping a version, run:

bash skills/sure-api/scripts/sure_api_acceptance.sh

Optional live API validation:

bash skills/sure-api/scripts/sure_api_acceptance.sh --with-live-api

The acceptance script checks:

• required files exist

• SKILL.md

  frontmatter is valid enough for publishing
• official URLs are present
• self-update instructions are present
• endpoint summary matches the checked-in OpenAPI
• optional live smoke test passes

ClawHub publish commands

First confirm login:

clawhub whoami

Initial publish example:

cd /root/.openclaw/workspace
clawhub publish ./skills/sure-api \
  --slug sure-api \
  --name "Sure API" \
  --version 1.0.0 \
  --changelog "Initial public release." \
  --tags latest

Update publish example:

cd /root/.openclaw/workspace
clawhub publish ./skills/sure-api \
  --slug sure-api \
  --name "Sure API" \
  --version 1.0.1 \
  --changelog "Refresh official OpenAPI, tighten docs, and improve publish readiness." \
  --tags latest

Notes for future maintenance

• Keep

  SKILL.md

  concise; put exact API detail in

  references/

  .
• Do not add README / CHANGELOG / extra docs just for packaging.
• Only wrap high-value flows in

  sure_api_cli.js

  ; leave long-tail official endpoints to the raw request wrapper.
• If upstream removes or renames endpoints, update examples and acceptance checks in the same commit.