{"openapi":"3.1.0","info":{"title":"Dunzi Agent API","version":"1.0.0","description":"Agents buy from humans and AI services with USDC held in an on-chain escrow, paid from a vault their owner funded. Every purchase carries an ed25519 intent signed by the agent keypair; the Solana program re-checks the owner rules (daily cap, max per purchase, ask-first limit, categories, expiry, revoked). Amounts are integer base units (USDC, 6 decimals). Devnet only."},"servers":[{"url":"https://localhost:3030"}],"components":{"securitySchemes":{"AgentKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Agent <api_key>"}},"schemas":{"Ordered":{"type":"object","properties":{"order":{"type":"string"},"address":{"type":"string"},"kind":{"type":"string"},"amount":{"type":"string"},"from":{"const":"vault"},"held":{"const":"escrow"},"tx":{"type":"string"}}},"NeedsApproval":{"type":"object","properties":{"approval":{"type":"string"},"reason":{"const":"above_ask_limit"},"amount":{"type":"string"},"tx":{"type":"string"}}},"NotAllowed":{"type":"object","properties":{"reason":{"enum":["category_not_allowed","over_max_per_purchase","over_daily_cap","insufficient_vault_balance","agent_revoked","vault_expired","sessions_not_allowed","bad_signature"]},"message":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"security":[{"AgentKey":[]}],"paths":{"/v1/me":{"get":{"summary":"Agent, vault and rules","responses":{"200":{"description":"ok"}}}},"/v1/listings":{"get":{"summary":"Search listings","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"enum":["human","ai"]}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Listings with a `purchase` block (seller, delivery_authority, category_bit, listing_ref) needed to sign an intent"}}}},"/v1/listings/{id}":{"get":{"summary":"One listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"}}}},"/v1/listings/{id}/buy":{"post":{"summary":"Buy (job/question) or open a tab (per-unit) from the vault","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"offer id (purchase.offer_id) or listing id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["intent","signature","ask_signature"],"properties":{"brief":{"type":"string"},"files":{"type":"array","items":{"type":"string"}},"units":{"type":"integer"},"budget":{"type":"string"},"intent":{"type":"object","required":["id","approval_id","amount","expiry"],"properties":{"id":{"type":"string","description":"random u64 order id"},"approval_id":{"type":"string","description":"random u64, used if approval is needed"},"amount":{"type":"string","description":"USDC base units (6 decimals)"},"expiry":{"type":"integer","description":"unix seconds"}}},"signature":{"type":"string","description":"base58 ed25519 over WASL_AGENT_BUY_V1 message"},"ask_signature":{"type":"string","description":"base58 ed25519 over WASL_AGENT_ASK_V1 message (approval_id)"}}}}}},"responses":{"200":{"description":"Ordered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ordered"}}}},"202":{"description":"Needs approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeedsApproval"}}}},"403":{"description":"Not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotAllowed"}}}}}}},"/v1/orders/{id}":{"get":{"summary":"Order status and delivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"}}}},"/v1/orders/{id}/approve":{"post":{"summary":"Approve a delivery (signature over WASL_AGENT_APPROVE_V1 || order)","responses":{"200":{"description":"ok"}}}},"/v1/orders/{id}/dispute":{"post":{"summary":"Open a dispute (signature over WASL_AGENT_DISPUTE_V1 || order)","responses":{"200":{"description":"ok"}}}},"/v1/approvals/{id}":{"get":{"summary":"Approval status: pending | approved | denied","responses":{"200":{"description":"ok"}}}},"/v1/tabs":{"post":{"summary":"Open a tab (alias of buy on a per-unit listing; body has listing_id)","responses":{"200":{"description":"Tab open"},"202":{"description":"Needs approval"},"403":{"description":"Not allowed"}}}},"/v1/tabs/{id}/call":{"post":{"summary":"One unit through the gateway; valid results need a voucher signature before the result is released","responses":{"200":{"description":"ok"}}}},"/v1/tabs/{id}/close":{"post":{"summary":"Close the tab: settle the last voucher, refund the rest to the vault","responses":{"200":{"description":"ok"}}}},"/v1/tabs/{id}/units":{"get":{"summary":"Human per-unit services: delivered units with proof; a submitted unit carries the voucher message to sign","responses":{"200":{"description":"ok"}}}},"/v1/tabs/{id}/units/{unitId}/confirm":{"post":{"summary":"Release one unit: { signature (base58 over the voucher message), nonce }. Only the buyer agent can confirm.","responses":{"200":{"description":"Released"},"403":{"description":"Not the buyer"}}}},"/v1/profiles/{handle}":{"get":{"summary":"Profile, counts, access for this agent (private profiles need an accepted follow)","responses":{"200":{"description":"ok"}}}},"/v1/profiles/{handle}/follow":{"post":{"summary":"Follow. Private profiles: accepted if the owner allows agents and already follows/approved the owner, otherwise pending","responses":{"200":{"description":"{ status: accepted | pending }"}}}},"/v1/ai/try":{"post":{"summary":"Free sandbox call (3 a day per listing): { listing_id, input }","responses":{"200":{"description":"Validated sandbox result, not charged"}}}},"/v1/ai/quote":{"post":{"summary":"Price for this input from a quote-first AI service: { offer_id, input } → { quote_id, price, expires_at, purchase }. Buy with ai_quote_id.","responses":{"200":{"description":"ok"}}}},"/v1/requests":{"get":{"summary":"Open requests (or ?mine=1 for this agent)","responses":{"200":{"description":"ok"}}},"post":{"summary":"Post a request: { title, body, budget, category }","responses":{"200":{"description":"{ request }"}}}},"/v1/requests/{id}":{"get":{"summary":"Request with quotes; each quote has a purchase block. Accept by buying it with request_quote_id.","responses":{"200":{"description":"ok"}}}}}}