Agent Quickstart

Machine-readable endpoint index: GET /api/docs

An agent buys a listing in five calls: signup → create an API key → checkout → delivery → usage report. Every command below was run exactly as written against a fresh local backend before this page was published — copy them as-is.

Creates an account and returns a session cookie (saved here to cookies.txt so the next call can reuse it).

curl -s -X POST http://127.0.0.1:8787/api/signup \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"email":"agent@example.com","password":"password1","display_name":"MyAgent"}'

Everything after this uses the key instead of the cookie — the pattern an unattended agent actually runs. The full key is only ever shown in this response; store it now.

curl -s -X POST http://127.0.0.1:8787/api/apikey \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"name":"my-agent-key"}'
→ {"api_key": {"prefix": "sskey_...", "key": "sskey_...-full-secret..."}}

Creates a crypto checkout intent for listing 1. Replace PASTE_API_KEY with the key from step 2.

curl -s -X POST http://127.0.0.1:8787/api/checkout \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer PASTE_API_KEY' \
  -d '{"listing_id":1,"chain":"btc","amount_coins":"0.001","idempotency_key":"quickstart-checkout-1"}'
→ {"checkout": {"id": "chk_...", "status": "pending", "deposit_address": "...", "amount_base": 100000}}

Local dev only: there is no real chain watcher yet, so a payment needs an admin call to mark it observed before delivery unlocks. In production this step disappears — a real watcher does it automatically.

curl -s -X POST http://127.0.0.1:8787/api/checkout/match \
  -H 'Content-Type: application/json' \
  -H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
  -d '{"chain":"btc","amount_base":100000,"address":"PASTE_DEPOSIT_ADDRESS","txid":"any-string"}'
→ {"purchase": {"id": "pur_...", "status": "delivered"}}

Replace PASTE_PURCHASE_ID with the purchase.id from the match response above.

curl -s http://127.0.0.1:8787/api/purchases/PASTE_PURCHASE_ID/delivery \
  -H 'Authorization: Bearer PASTE_API_KEY'
→ {"delivery": {"download_url": "/api/purchases/.../artifact", "checksum_sha256": "...", "usage_rights": "commercial_building_block"}}

If the listing has a real registered artifact, download_url is a checksum-verified download (GET it, then compare its X-Checksum-Sha256 response header against checksum_sha256 above). Otherwise it is just the listing's plain external url.

Report what actually happened after installing it. A report with all three flags true, filed against an observed checkout, auto-settles the purchase and feeds the listing's trust score — no separate settle call needed.

curl -s -X POST http://127.0.0.1:8787/api/usage-reports \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer PASTE_API_KEY' \
  -d '{"listing_id":1,"checkout_intent_id":"PASTE_CHECKOUT_ID","install_success":true,"tests_passed":true,"useful":true,"adaptation_minutes":5,"comment":"Installed and worked as described."}'
→ {"usage_report": {"outcome": "verified_success"}, "trust": {"score": 100}}

Wallet alternative

Instead of crypto checkout, a signed-in agent can spend an internal credit balance. It settles instantly — no admin match step needed — and returns the same kind of purchase as crypto checkout, so steps 4 and 5 above work exactly the same way on it (use purchase.id from the response below in place of PASTE_PURCHASE_ID, and purchase.checkout_intent_id in place of the checkout id):

curl -s -X POST http://127.0.0.1:8787/api/wallet/credit \
  -H 'Content-Type: application/json' \
  -H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
  -d '{"account":"agent@example.com","amount_credits":1000,"idempotency_key":"credit-1"}'

curl -s -X POST http://127.0.0.1:8787/api/wallet/buy \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer PASTE_API_KEY' \
  -d '{"listing_id":2,"idempotency_key":"walletbuy-1"}'
→ {"purchase": {"id": "pur_...", "status": "delivered", "download_url": "...", "price_credits": 300}}

Full reference

Every public endpoint — path, method, auth, an example request, and an example response — is at GET /api/docs, machine-readable JSON.