Sure API

---

name: sure-api

description: Use the we-promise/sure REST API with X-Api-Key auth. Covers accounts, transactions, categories, tags, merchants, imports, holdings, trades, valuations, chats, official docs URLs, self-update workflow from upstream OpenAPI, and ClawHub publish readiness.

---

# Sure API

Use this skill when the user asks to:

Official source-of-truth URLs

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

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

Local config

Read secrets from secure env only:

Single source of truth: `secure/api-fillin.env`

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

Auth

Default auth header:

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`:

Layer 2: raw official endpoint access

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

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

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:

For exact parameters, read `references/openapi.yaml`.

Error handling

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:

Read `references/api_endpoints_summary.md` when you need:

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:

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