{ "openapi": "3.1.0", "info": { "title": "BUSK Agent API", "version": "1.0.0", "description": "Agents buy finished work from BUSK shops: a capped quote, one USDC payment into a per-order escrow on Solana (the agent wallet signs place_order first, the server co-signs last), delivery with a hash written on chain, settlement after a 72-hour confirm window or on the buyer's confirmation. Docs: https://busk.live/agents" }, "servers": [ { "url": "https://busk.live" } ], "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "busk_ak_...", "description": "Agent key from POST /api/v1/studio/agent-keys" }, "session": { "type": "apiKey", "in": "cookie", "name": "rt_session", "description": "Sign-In With Solana session from POST /api/auth/verify" } }, "schemas": { "Ok": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": {} } }, "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "QUOTE_EXPIRED" ] }, "message": { "type": "string" }, "details": {} } } } }, "Options": { "type": "object", "description": "Option id -> value (number, string up to 64 chars, or boolean), at most 32 keys", "additionalProperties": { "type": [ "number", "string", "boolean" ] } }, "Material": { "oneOf": [ { "type": "object", "title": "Wallet recap", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "description": "A public Solana wallet address" } } }, { "type": "object", "title": "Reaction pack", "required": [ "refs", "rightsConfirmed" ], "properties": { "refs": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string" }, "description": "Upload refs made with the same key" }, "rightsConfirmed": { "const": true }, "reactions": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9 !?'-]{1,24}$" } } } } ] }, "Quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "productId": { "type": "string" }, "shopSlug": { "type": "string" }, "options": { "$ref": "#/components/schemas/Options" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "amountUsd": { "type": "number" } } } }, "totalUsd": { "type": "number" }, "capUsd": { "type": "number" }, "split": { "type": "object", "properties": { "generationUsd": { "type": "number" }, "platformFeeUsd": { "type": "number" }, "platformFeePct": { "type": "number" }, "shopUsd": { "type": "number" } } }, "currency": { "const": "USDC" }, "turnaroundMin": { "type": "integer" }, "validForMin": { "type": "integer" }, "validUntil": { "type": "string", "format": "date-time" }, "preset": { "type": [ "object", "null" ] } } }, "AgentOrder": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" }, "tx": { "type": "string", "description": "base64 place_order transaction, unsigned; the agent wallet is account 0" }, "validUntil": { "type": "string", "format": "date-time" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "const": "solana-escrow" }, "mint": { "type": "string", "description": "USDC mint" }, "amount": { "type": "string", "description": "Base units (6 decimals)" }, "recipient": { "type": "string", "description": "The order's escrow account" }, "quoteId": { "type": "string" } } } } } }, "Order": { "type": "object", "description": "The order view: state is quote | order | making | handoff | settled | failed | refunded | cancelled", "properties": { "id": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" }, "shopSlug": { "type": "string" }, "shopName": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "buyer": { "type": "string" }, "buyerKind": { "enum": [ "person", "agent" ] }, "state": { "enum": [ "quote", "order", "making", "handoff", "settled", "failed", "refunded", "cancelled" ] }, "quote": { "$ref": "#/components/schemas/Quote" }, "progress": { "type": [ "object", "null" ], "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "label": { "type": "string" } } }, "deliverables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "File name" }, "name": { "type": "string" }, "format": { "type": "string" }, "sizeLabel": { "type": "string" }, "art": { "type": "object", "properties": { "kind": { "const": "asset" }, "url": { "type": "string", "description": "GET with the same key" }, "mime": { "type": "string" } } } } } }, "settlement": { "type": [ "object", "null" ] }, "failure": { "type": [ "object", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } }, "proofTx": { "type": [ "string", "null" ], "description": "Latest on-chain step; public record at /proof/tx/{proofTx}" } } } }, "responses": { "Error": { "description": "Failure envelope (see error codes in the docs)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/auth/nonce": { "post": { "summary": "One-time Sign-In With Solana message", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string" } } } } } }, "responses": { "200": { "description": "Message to sign (valid 5 minutes)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "nonce": { "type": "string" }, "message": { "type": "string" }, "expiresAt": { "type": "string" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/auth/verify": { "post": { "summary": "Verify the signed message and open a session (Set-Cookie rt_session, 7 days)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet", "nonce", "signature" ], "properties": { "wallet": { "type": "string" }, "nonce": { "type": "string" }, "signature": { "type": "string", "description": "ed25519 over the message bytes, base58 or base64" } } } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "wallet": { "type": "string" } } }, "expiresAt": { "type": "string" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/studio/agent-keys": { "get": { "summary": "This wallet's agent keys (no secrets)", "security": [ { "session": [] } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create an agent key (returned once)", "security": [ { "session": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "perOrderUsd", "dailyUsd" ], "properties": { "label": { "type": "string", "maxLength": 40 }, "perOrderUsd": { "type": "number", "minimum": 0.1, "maximum": 1000 }, "dailyUsd": { "type": "number", "maximum": 10000, "description": "At least perOrderUsd; per UTC day" }, "agentWallet": { "type": "string", "description": "Binds the key to this paying wallet" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "agentWallet": { "type": [ "string", "null" ] }, "perOrderUsd": { "type": "number" }, "dailyUsd": { "type": "number" }, "createdAt": { "type": "string" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/studio/agent-keys/{id}": { "delete": { "summary": "Revoke a key", "security": [ { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "revoked": { "const": true } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/shops": { "get": { "summary": "Shops open on chain with at least one live product", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "reaction-pack", "wallet-recap" ] } }, { "name": "sort", "in": "query", "schema": { "enum": [ "orders", "newest", "price", "speed" ] } } ], "responses": { "200": { "description": "Shop summaries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/shops/{slug}": { "get": { "summary": "One shop with its live products and options", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Shop slug", "schema": { "type": "string", "pattern": "^[a-z0-9-]{3,40}$" } } ], "responses": { "200": { "description": "Shop", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agent/orders/quote": { "post": { "summary": "A capped quote (valid 15 minutes, one use, this key only)", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shopSlug", "productId" ], "properties": { "shopSlug": { "type": "string" }, "productId": { "type": "string" }, "options": { "$ref": "#/components/schemas/Options" }, "presetId": { "type": "string", "description": "Pro and Max shops: a brand preset id or \"none\"" }, "agentWallet": { "type": "string", "description": "Required when the key is not bound to a wallet" } } } } } }, "responses": { "201": { "description": "Quote", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/uploads": { "post": { "summary": "Upload a reference image (PNG, JPEG or WebP, up to 5 MB)", "security": [ { "agentKey": [] }, { "session": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ref": { "type": "string" }, "sha256": { "type": "string" }, "bytes": { "type": "integer" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agent/orders": { "post": { "summary": "Create the order and its unsigned place_order transaction", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "material" ], "properties": { "quoteId": { "type": "string", "format": "uuid" }, "material": { "$ref": "#/components/schemas/Material" }, "agentWallet": { "type": "string" } } } } } }, "responses": { "202": { "description": "Order created, payment transaction issued", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentOrder" } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agent/orders/{id}/submit": { "post": { "summary": "Send the wallet-signed transaction (server verifies, co-signs, sends)", "security": [ { "agentKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "signedTx" ], "properties": { "signedTx": { "type": "string", "description": "base64" } } } } } }, "responses": { "200": { "description": "Funded", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "signature": { "type": "string" }, "order": { "$ref": "#/components/schemas/Order" } } } } } ] } } } }, "202": { "description": "Sent, not confirmed yet: call again with the same body", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "signature": { "type": "string" }, "order": { "$ref": "#/components/schemas/Order" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agent/orders/{id}": { "get": { "summary": "The order (key that placed it)", "security": [ { "agentKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/files/{orderId}/{file}": { "get": { "summary": "A delivered file", "security": [ { "agentKey": [] }, { "session": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } }, { "name": "file", "in": "path", "required": true, "description": "File name", "schema": { "type": "string" } }, { "name": "download", "in": "query", "schema": { "const": "1" } } ], "responses": { "200": { "description": "File bytes" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/orders/{id}/confirm": { "post": { "summary": "Accept the delivery early (session of the buyer wallet)", "security": [ { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signedTx": { "type": "string", "description": "Leave out to get the settle_order transaction" } } } } } }, "responses": { "200": { "description": "Transaction to sign, or settled", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "tx": { "type": "string" }, "signature": { "type": "string" }, "order": { "$ref": "#/components/schemas/Order" } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/orders/{id}/cancel": { "post": { "summary": "Cancel before making starts (paid orders are refunded in full)", "security": [ { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/orders/{id}/showcase": { "post": { "summary": "Show (or hide) the delivered files on the public proof", "security": [ { "agentKey": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string", "pattern": "^BSK-[0-9A-Z]{8}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "public" ], "properties": { "public": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ok" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "order": { "type": "string" }, "public": { "type": "boolean" }, "at": { "type": [ "string", "null" ] } } } } } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } } } }