Agent quickstart

Base URL https://api.cofferline.com/v1 (below: $API). Every mutation accepts Idempotency-Key. Every error answers {code, message, remediation, docs_url} — the remediation is the fix. Schemas: https://api.cofferline.com/openapi.json. Prices: the manifest pricing object (https://cofferline.com/.well-known/cofferline.json). Machine-executable form of this page: https://cofferline.com/quickstart.json. Terms are hash-referenced in the manifest; custody matrix: https://cofferline.com/legal/custody.json.

1 · Authenticate (SIWE — the wallet is the account)

curl -X POST $API/auth/challenge -d '{"address":"0xYOU"}'
# → {message, …} — sign `message` with your key (EOA, EIP-1271, or ERC-6492)
curl -X POST $API/auth/verify -d '{"message":"…","signature":"0x…"}'
# → {token:"cl_sess_…"} — Bearer for everything below
curl -X POST $API/keys -H "Authorization: Bearer cl_sess_…"   # durable cl_key_…

Shortcut: a valid x402 payment (§2) authenticates by itself — the payer address becomes the account. One signed request = registered + funded. Fleets: POST $API/keys/enroll mints one wallet-scoped key per agent in one call.

2 · Fund the fee balance (x402, USDC — the payer needs zero ETH)

curl -X POST $API/balance/topup -d '{"amount_usd":"5"}'            # → 402 + accepts[]
# sign accepts[0] as an EIP-3009 transferWithAuthorization, retry with the header:
curl -X POST $API/balance/topup -H "X-PAYMENT: <base64 payload>" -d '{"amount_usd":"5"}'
# → 202; the credit lands at Base finality (minutes), exactly once. Poll:
curl $API/balance -H "Authorization: Bearer …"

Fees debit this balance ($0.20 + 10 bps of notional per conversion intent). Never hit a mid-workflow 402: PUT $API/balance/auto-topup with pre-signed authorizations.

3 · Set the policy (3 fields; everything else defaults conservatively)

curl -X PUT $API/policies -H "Authorization: Bearer …" \
  -d '{"version":1,"wallet":"0xACCOUNT","chain_id":8453}'
# → the full effective document + `defaulted` (every path the platform filled)

wallet is your Kernel v3.1 smart account (§4), not your EOA. Defaults are written INTO the stored document — read back with GET $API/policies; the full default set is the manifest's policies.defaults, per-field docs at https://cofferline.com/schemas/policy-v1.json. One to know: execution.venues is ORDERED — the first entry is the routing preference. A change is one PUT: new immutable version.

4 · Convert (swap) — one smart account + one delegation

Your EOA owns a Kernel v3.1 account (factory salt 0; any 4337 tooling derives it). It may stay undeployed — the first delegated execution deploys it. Fund it with the tokens to trade plus a little ETH: it pays its own execution gas.

# grant the two calls a swap makes: approve on the sell token + the venue router
# (a missing grant aborts POLICY_VIOLATION naming the exact target+selector to add)
curl -X POST $API/delegations/prepare -H "Authorization: Bearer …" -d '{
  "account":"0xKERNEL","chain_id":8453,"valid_until":1790000000,
  "calls":[{"target":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","selector":"0x095ea7b3","value_limit":"0"}]}'
# → {id, digest} — sign digest with the OWNER key, then:
curl -X POST $API/delegations/{id}/confirm -d '{"enable_sig":"0x…","owner":"0xYOU"}'

# the trade — token ADDRESSES, base-unit amounts ("1000000" = $1 of 6-decimal USDC):
curl -X POST $API/intents -H "Authorization: Bearer …" -d '{
  "wallet":"0xKERNEL","kind":"conversion",
  "sell_token":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","buy_token":"0x4200000000000000000000000000000000000006","sell_amount":"1000000"}'
curl $API/intents/{id}     # planned → executing → filled; fills + report inline

Free preview first: POST $API/quotes (no auth) runs the SAME planner against live venue quotes. Gas top-ups: "kind":"gas_topup", or automatic below the policy's gas.floor. Revoking the delegation is your own on-chain transaction — it never requires Cofferline.

Prediction-market agents (Polymarket)

A Polymarket signer key is a full owner of your funder wallet (the venue's design): use a dedicated signer EOA and a dedicated funder holding only working trading balances. Credentials are sealed write-only — no endpoint returns them, revocation zeroes them, every use is audited (security.alert webhooks). Jurisdiction gating mirrors the venue's geo-restrictions.

curl -X POST $API/pm/credentials …      # BYO trade-scoped credential, verified live against the venue
curl $API/pm/onboarding/{address}       # required on-chain approvals + owner-signable calldata
curl -X PUT $API/policies …             # prediction_markets: {per_market_cap_usd, daily_loss_stop_usd,
                                        #   max_resolution_exposure_usd, market_allowlist?, exposure_basis? gross|net}
curl -X POST $API/checks/pm-order …     # free pre-flight: would this order pass right now?
curl -X POST $API/pm/orders …           # LIMIT only; a refused order names the violated rule, never transmits
curl -X DELETE $API/pm/orders/{venue}/{order_id}   # cancels are FREE — reduce risk over a fee
curl -X POST $API/pm/fills/sync         # journal venue fills into the ledger (idempotent; feeds the exposure floor)

Signer rotation: GET $API/pm/credentials/{id}/rotation?new_owner=0x… returns the Safe swapOwner calldata; execute it from your funder yourself, POST the new key, DELETE the old (ciphertext zeroed).

Read the books

curl "$API/statements?wallet=0x…&period=YYYY-MM"   # deterministic, content-addressed (JSON or CSV)
curl $API/events                                    # typed event stream; webhooks per wallet policy
curl $API/balance                                   # prepaid fee balance

Same period twice = identical bytes, derived from the ledger. Every fill, fee, and top-up is a row.