sure-api（sure API 文档）

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\
2026-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.