{ "openapi": "3.1.0", "info": { "title": "agents.u.cash", "version": "0.7.1", "description": "Agent + merchant product surface for the 402 Online Protocol - multi-coin, non-custodial HTTP-402 payments. Two-sided: sell (get paid to your own wallet) and buy (pay for resources). UCP (ucp.dev) discovery + multi-item mixed-currency checkout sessions + AP2 mandates + RFC 9421-signed responses. Live reference implementation; protocol spec at https://402.onl. INPUT CONTRACTS (all authenticated writes): unknown keys are rejected with 400 uxc_unknown_param listing the Allowed keys; wrong shapes are rejected with 400 uxc_invalid_request naming the field and expected shape; booleans must be true/false (or \"true\"/\"false\"); updates are true partials (unsent fields keep their values). Supported assets (grouped; the engine master list): Bitcoin (BTC, +Lightning), Ethereum (ETH), Solana (SOL), Tron (TRX), XRP, Dogecoin (DOGE), Litecoin (LTC), Bitcoin Cash (BCH), Algorand (ALGO), Monero (XMR), Polkadot (DOT), Stellar (XLM), Tezos (XTZ), Polygon (POL), Avalanche (AVAX), BNB Chain (BNB), Toncoin (TON); Base, Arbitrum, Optimism, Linea, Mantle, Berachain, Sonic, Unichain, World, Monad, Plasma, Abstract, Scroll, Ink, Hyperliquid (native gas + ETH-bridged), Robinhood Chain (native gas + ALL 194 issuer-listed tokenized-asset rails; featured set in pickers, u.cash/tokenized-assets for the full list); USDT (Ethereum / BSC / Tron), USDC (Ethereum), and USDC-on-Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) - the x402 gasless rail; UCASH (Ethereum ERC-20, 0x92e52a1A235d9A103D970901066CE910AAceFD37) - also the non-withdrawable fee-credit unit; Any ERC-20 / BEP-20 / Base-20 / Polygon-20 / Arb-20 / Op-20 / Avax-20 / Linea / Mantle / Sonic / Bera / ... / TRC-20 / SPL / TON Jetton / Robinhood-20 added via POST /v1/custom-tokens (auto-detected on-chain like any coin)", "contact": { "url": "https://github.com/UdotCash/agents" } }, "servers": [ { "url": "https://agents.u.cash", "description": "agents.u.cash" } ], "tags": [ { "name": "Account", "description": "Signup, activation, wallets, webhook, settlement log" }, { "name": "Storefront", "description": "Read/edit the agent's own storefront (Shop Page): chrome, free-canvas layout, custom templates, image assets" }, { "name": "Sell (402)", "description": "Create resources + build the multi-coin accepts[]" }, { "name": "Buy", "description": "Fetch the 402 door, pay, and settle a payment (public)" }, { "name": "Prime", "description": "Member-consented access to prime.u.cash: link claim, champion roster and sheets, act/explore/games/pvp/tournaments/studio/inventions writes, quests + feed reads. Scopes: prime.read, prime.characters.read, prime.characters.act, prime.explore.act, prime.games.act, prime.pvp.act, prime.pvp.wager, prime.tournaments.act, prime.tournament.entry, prime.inventions.propose, prime.studio.spend, prime.feed.read. UNITS/day spend grants (studio, pvp wagers, heat entries) fail closed; agent-attributed play earns a reduced UNITS rate with full training and XP." }, { "name": "UCP", "description": "Universal Commerce Protocol: discovery + multi-item checkout sessions + AP2 mandates (public; merchant resolved from host or ?cloud=)" }, { "name": "Subagents", "description": "Owner-only: delegate scoped sa_ API keys with a limited RBAC role (create/list/update/rotate/delete)" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "The api_key from POST /v1/signup." } }, "schemas": { "Signup": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "primary_wallet": { "type": "string" }, "agreed_to_terms": { "type": "boolean", "description": "Send true to agree to the Terms of Service (https://u.cash/legal/terms). An explicit false is rejected; omitted is treated as agreed for backward compatibility." } } }, "Wallet": { "type": "object", "required": [ "asset", "address" ], "properties": { "asset": { "type": "string", "description": "cryptocurrency code, e.g. btc, eth, sol, trx, usdt, usdc, ucash, usdc_base (the x402 gasless rail); or a custom-token code you added via /v1/custom-tokens" }, "address": { "type": "string" } } }, "Resource": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "fiat price, e.g. 0.05" }, "currency": { "type": "string", "default": "USD" }, "accepted_assets": { "type": "array", "items": { "type": "string" }, "description": "defaults to all configured wallets" }, "webhook_url": { "type": "string", "format": "uri", "description": "notified (HMAC-signed) on settlement" }, "max_per_caller": { "type": "object", "description": "optional per-caller spend cap; a payer whose settled spend in the window reaches amount is refused new authorization", "properties": { "amount": { "type": "number" }, "window_hours": { "type": "integer" }, "by": { "type": "string", "enum": [ "wallet", "ip" ], "default": "wallet", "description": "wallet = enforce at verify/settle; ip = enforce at the door before charge" } } }, "checkout_url": { "type": "string", "format": "uri", "description": "response field: the canonical buyer door on pay.u.cash (/checkout/?cloud=). A human gets the HTML checkout; an agent fetches ?agent=1 for the 402 manifest; an x402 client sends X-PAYMENT" }, "test": { "type": "boolean", "description": "test mode: settles instantly for $0, no wallet needed, marked in responses, excluded from earnings" }, "test_confirmations": { "type": "integer", "minimum": 0, "maximum": 12, "default": 1, "description": "sandbox only: simulated confirmations required before settle (POST /v1/simulate-payment advances them; default 1 = instant, like the historic behavior)" } } }, "Verify": { "type": "object", "required": [ "challengeId", "hash" ], "properties": { "challengeId": { "type": "string", "description": "from an accepts[] entry" }, "hash": { "type": "string", "description": "on-chain transaction hash" } } }, "Stripe": { "type": "object", "required": [ "secret_key", "product_id", "webhook_secret" ], "description": "Your own Stripe account keys - enables the card (redirect) rail. Verified against Stripe before storing; secrets are never returned in full.", "properties": { "secret_key": { "type": "string", "description": "sk_live_... or sk_test_..." }, "product_id": { "type": "string", "description": "a one-time product id (prod_...)" }, "webhook_secret": { "type": "string", "description": "whsec_... from registering the webhook endpoint" }, "publishable_key": { "type": "string", "description": "optional pk_live_... or pk_test_..." } } }, "CheckoutSession": { "type": "object", "required": [ "line_items" ], "description": "UCP buyer checkout (multi-item, mixed-currency). The merchant is resolved from the host or ?cloud=, NOT X-Api-Key.", "properties": { "line_items": { "type": "array", "description": "one entry per item", "items": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "string", "description": "resource res_id or checkout slug" } } }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } } } }, "currency": { "type": "string", "description": "cart currency for mixed-currency carts (default: the shared item currency, else the merchant default)" }, "buyer": { "type": "object" }, "context": { "type": "object" } } }, "Ap2": { "type": "object", "description": "AP2 mandate (dev.ucp.shopping.ap2_mandate) - optional holder-proof buyer authorization on complete.", "properties": { "checkout_mandate": { "type": "string", "description": "buyer-signed SD-JWT-VC binding the payment to this checkout" } } } } }, "paths": { "/v1/signup": { "post": { "tags": [ "Account" ], "summary": "Register an agent account (returns the api_key immediately; usable at $0; email verification is optional and grants $5 free credit (up to $2,500 in transactions))", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signup" } } } }, "responses": { "200": { "description": "{api_key, activated, next}" }, "400": { "description": "validation error" } } } }, "/v1/top-up": { "post": { "tags": [ "Account" ], "summary": "Create a credit top-up checkout (>= $1; adds platform credit; email verification is the activation gate; allowed pre-activation)", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 1 } } } } } }, "responses": { "200": { "description": "{url, amount, activated, next}" } } } }, "/v1/agent": { "get": { "tags": [ "Account" ], "summary": "Account snapshot: activation, balance, wallets, webhook URL, earnings summary", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{email, activated, primary_wallet, credit_balance, webhook_url, wallets, settlements_count, total_earned}" } } }, "post": { "tags": [ "Account" ], "summary": "Set the settlement webhook URL {webhook_url}", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string" } } } } } }, "responses": { "200": { "description": "{webhook_url}" } } } }, "/v1/me": { "get": { "tags": [ "Account" ], "summary": "Alias of /v1/agent (account snapshot).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "same as /v1/agent" } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Alias of /v1/agent (account snapshot).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "same as /v1/agent" } } } }, "/v1/webhooks": { "get": { "tags": [ "Account" ], "summary": "Webhook discoverability alias (canonical surface is /v1/webhook).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{webhook_url, how_to_set, rotate_secret}" } } } }, "/v1/webhook": { "get": { "tags": [ "Account" ], "summary": "Read the settlement webhook (masked): {url, has_secret, secret_last4}. Live-key only (sandbox keys get 403).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{url, has_secret, secret_last4}" } } }, "post": { "tags": [ "Account" ], "summary": "Set the webhook URL (auto-generates the HMAC secret on first set, shown once), rotate the secret ({rotate_secret:true}), or clear ({url:''}). Writes need the settings.edit capability for a subagent key. Live-key only (sandbox keys get 403 uxc_sandbox_key_rejected).", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "rotate_secret": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{url, secret}" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit) | uxc_sandbox_key_rejected (sandbox key)" } } }, "delete": { "tags": [ "Account" ], "summary": "Clear the webhook URL. settings.edit capability for a subagent key. Live-key only (sandbox keys get 403).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{url:'', cleared:true}" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit) | uxc_sandbox_key_rejected (sandbox key)" } } } }, "/v1/wallets": { "get": { "tags": [ "Account" ], "summary": "Your receive addresses {wallets{asset:address}}.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{wallets:{asset:address}}" } } }, "post": { "tags": [ "Account" ], "summary": "Set the agent's own receive address for an asset (where buyer funds land; accepts comma-separated for the Address List).", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "responses": { "200": { "description": "{asset, address}" }, "400": { "description": "uxc_unknown_asset | uxc_bad_address" } } }, "put": { "tags": [ "Account" ], "summary": "Toggle a coin on/off (?asset=, body {active:true|false}) without losing its address. GET ?all=1 lists paused coins.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{asset, active}" }, "400": { "description": "uxc_unknown_asset | uxc_invalid_request" } } }, "delete": { "tags": [ "Account" ], "summary": "Remove a coin receive address (?asset=); the coin stops being accepted until set again.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{asset, deleted:true}" }, "400": { "description": "uxc_unknown_asset | uxc_invalid_request" } } } }, "/v1/stripe": { "get": { "tags": [ "Account" ], "summary": "Masked Stripe config + the webhook endpoint to register", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{configured, active, mode, secret_key(masked), product_id, webhook_secret(masked), publishable_key, webhook_endpoint, webhook_events}" } } }, "post": { "tags": [ "Account" ], "summary": "Connect the agent's OWN Stripe account (card rail); verifies the key + product against Stripe, then stores. payments.processors.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stripe" } } } }, "responses": { "200": { "description": "masked config + webhook_endpoint" }, "400": { "description": "uxc_invalid_request | uxc_stripe_invalid" }, "403": { "description": "uxc_forbidden (subagent key without payments.processors.edit)" } } }, "delete": { "tags": [ "Account" ], "summary": "Disconnect Stripe (disables card payments). payments.processors.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{configured:false, cleared:true}" }, "403": { "description": "uxc_forbidden (subagent key without payments.processors.edit)" } } } }, "/v1/custom-tokens": { "get": { "tags": [ "Account" ], "summary": "List the agent custom tokens", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{custom_tokens:[{code,type,network,name,contract_address,decimals}]}" } } }, "post": { "tags": [ "Account" ], "summary": "Add a custom token (ERC-20/TRC-20/SPL/TON Jetton/Robinhood-20); then POST /v1/wallets to set its receive address. Auto-detected on-chain like any coin. settings.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "code", "contract_address", "decimals", "name" ], "properties": { "type": { "type": "string", "enum": [ "erc-20", "bep-20", "base-20", "polygon-20", "arb-20", "op-20", "avax-20", "trc-20", "spl", "ton-jetton", "robinhood-20" ] }, "code": { "type": "string" }, "contract_address": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 }, "name": { "type": "string" }, "rate": { "type": "string" }, "rate_url": { "type": "string", "description": "live rate source: an https URL returning a price JSON, or the coingecko: scheme (e.g. coingecko:nvidia-xstock; pattern ^coingecko:[a-z0-9][a-z0-9_-]{0,80}$) resolved server-side via CoinGecko" }, "confirmations": { "type": "integer", "minimum": 0, "maximum": 200 }, "img": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "the stored token" }, "400": { "description": "uxc_invalid_request | uxc_custom_token_exists" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit)" } } }, "delete": { "tags": [ "Account" ], "summary": "Remove a custom token by code. settings.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{deleted, custom_tokens}" }, "404": { "description": "uxc_not_found" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit)" } } } }, "/v1/settings": { "get": { "tags": [ "Account" ], "summary": "The agent safe settings: confirmations policy (default + per-coin + value-increase), webhook url (+ masked secret), currency, address_reuse_cooldown, payment preferences, notification email, branding", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{confirmations:{default,coins,increase}, webhook:{url,has_secret,secret_last4}, currency, address_reuse_cooldown, payment:{accept_underpayments,redirect}, notifications:{email}, branding:{brand_name,logo_url,logo_url_dark,color_1,color_2,color_3}}" } } }, "put": { "tags": [ "Account" ], "summary": "Partially update the agent safe settings (any subset). webhook.rotate_secret=true mints a new signing secret. No custodial/node/private-key/payout fields.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmations": { "type": "object" }, "webhook": { "type": "object" }, "currency": { "type": "string" }, "payment": { "type": "object" }, "notifications": { "type": "object" }, "branding": { "type": "object" }, "web3_names": { "type": "object" } } } } } }, "responses": { "200": { "description": "the full updated shape" } } } }, "/v1/settlements": { "get": { "tags": [ "Account" ], "summary": "The agent's earnings log (settled + underpaid resource payments)", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{settlements:[...]}" } } } }, "/v1/integrations": { "get": { "tags": [ "Account" ], "summary": "Read third-party integration credentials you have stored (Discord, Telegram, BigCommerce, Ecwid, Wix). Returned in plaintext to the authenticated agent. settings.edit capability for a subagent key (reads expose secrets).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{integrations:{discord?,telegram?,bigcommerce?,ecwid?,wix?}}" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit)" } } }, "put": { "tags": [ "Account" ], "summary": "Write third-party integration credentials. settings.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "object" } } } } } }, "responses": { "200": { "description": "{integrations:{...}}" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit)" } } } }, "/v1/account-email": { "post": { "tags": [ "Account" ], "summary": "OWNER KEY ONLY (an sa_ subagent key gets 403 uxc_forbidden). Add/change the account email (sends verification; login anchor + encryption key stay stable so wallets keep decrypting). Verifying grants $5 free credit (up to $2,500 in transactions).", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "{email, verification_required, next}" }, "403": { "description": "uxc_forbidden when authenticated with a subagent key" } } } }, "/v1/reset-password": { "post": { "tags": [ "Account" ], "summary": "OWNER KEY ONLY (an sa_ subagent key gets 403 uxc_forbidden). Reset the overseer web-login password (no-email agents have no email-reset path)", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "new_password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "{reset:true}" }, "403": { "description": "uxc_forbidden when authenticated with a subagent key" } } } }, "/v1/resend-verification": { "post": { "tags": [ "Account" ], "summary": "Resend the email verification link (3-day expiry for agents; no-op if already verified)", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{sent, next}" } } } }, "/v1/subagents": { "get": { "tags": [ "Subagents" ], "summary": "List the agent subagents (scoped sa_ API keys; never returns the api_key). Owner-only.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{subagents:[{id,role,role_name,permissions,store_scope,status,display_name,created_at}], balance, prices, slots_free}" } } }, "post": { "tags": [ "Subagents" ], "summary": "Create a subagent with a limited role (or custom permissions). The sa_ api_key is returned ONCE; a subagent with no free slot debits credit_balance. Owner-only. (POST ?subagent_id=N&rotate=key rotates the key.)", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "clerk|teller|lead|supervisor|manager|director|officer|admin|master-admin|accountant|auditor|designer|custom" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "custom-role capability slugs (e.g. transactions.view, checkouts.edit, payment-links.create)" }, "role_name": { "type": "string" }, "display_name": { "type": "string" }, "store_scope": { "type": "array", "items": { "type": "integer" }, "description": "restrict to these store ids (empty = all)" } } } } } }, "responses": { "200": { "description": "{api_key, subagent, seat_fee, slot, new_balance}" }, "402": { "description": "uxc_insufficient_balance" } } }, "put": { "tags": [ "Subagents" ], "summary": "Update a subagent role/permissions/store_scope/status/display_name. ?subagent_id=N. Owner-only.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "subagent_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "role_name": { "type": "string" }, "display_name": { "type": "string" }, "store_scope": { "type": "array", "items": { "type": "integer" } }, "status": { "type": "string", "enum": [ "active", "suspended" ] } } } } } }, "responses": { "200": { "description": "{subagent, seat_fee}" } } }, "delete": { "tags": [ "Subagents" ], "summary": "Delete a subagent (its key stops authenticating; the seat slot frees). ?subagent_id=N. Owner-only.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "subagent_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted, id}" } } } }, "/v1/site": { "get": { "tags": [ "Storefront" ], "summary": "Read the agent's storefront (Shop Page): shop-* chrome values, free-canvas layout, themes/layouts, style vars. ?resource=templates lists custom templates; ?resource=templates&id=N fetches one.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "resource", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{site:{values, template, themes, layouts, layout, style_vars}} | {templates:[...]} | {template:{...}}" } } }, "put": { "tags": [ "Storefront" ], "summary": "Update the storefront chrome (shop-* only, merged) and/or the free-canvas layout: {chrome?, layout?}. Or update a custom template: ?resource=templates&id=N {chrome, css?, layout?}. Non-GET ops need the design.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "resource", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "chrome": { "type": "object", "additionalProperties": true }, "layout": { "type": "object" } } } } } }, "responses": { "200": { "description": "{saved:true}" }, "403": { "description": "uxc_forbidden (subagent key without design.edit)" } } }, "post": { "tags": [ "Storefront" ], "summary": "Create a custom template (?resource=templates {name, base_template?, base_theme?, chrome, css?, layout?}), apply one (?resource=templates&action=apply&id=N), or upload an image (?resource=assets, multipart file). design.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "resource", "in": "query", "schema": { "type": "string" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{id, saved:true} | {applied:true} | {url}" }, "403": { "description": "uxc_forbidden (subagent key without design.edit)" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Delete a custom template: ?resource=templates&id=N. design.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "resource", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted:true}" }, "403": { "description": "uxc_forbidden (subagent key without design.edit)" } } } }, "/v1/resources": { "post": { "tags": [ "Sell (402)" ], "summary": "Create a priced resource (optional max_per_caller to cap a payer's spend in a window). Optional Idempotency-Key header makes retried creates replay instead of duplicating.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "retry-safe create: the same key + body replays the original response (Idempotency-Replayed: true) instead of duplicating" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "responses": { "200": { "description": "{res_id, amount, currency, accepted_assets, max_per_caller, checkout_url}" } } }, "put": { "tags": [ "Sell (402)" ], "summary": "Set (or clear) a resource's per-caller spend cap. ?res_id=N { max_per_caller: {amount, window_hours} | null }", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "res_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "max_per_caller": { "$ref": "#/components/schemas/Resource/properties/max_per_caller" } } } } } }, "responses": { "200": { "description": "{res_id, max_per_caller}" } } }, "get": { "tags": [ "Sell (402)" ], "summary": "List resources, fetch one (?res_id=, incl. max_per_caller), or its per-caller spend ledger (?res_id=N&callers=1)", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{resources:[...]} | one resource | {callers:[{caller,spend,payments}]}" } } }, "delete": { "tags": [ "Sell (402)" ], "summary": "SOFT disable a resource: removes it from the list and the /r/ door but keeps its settled history in GET /v1/settlements. ?res_id=N", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "res_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{disabled:true, res_id}" } } } }, "/v1/payment-requests": { "post": { "tags": [ "Sell (402)" ], "summary": "Create a ONE-OFF payment request (a pay.u.cash /id/ link that closes when paid or after the expiry). Distinct from resources (persistent).", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "default": "USD" }, "asset": { "type": "string" }, "asset_amount": { "type": "number" }, "cryptocurrency": { "type": "string" }, "title": { "type": "string" }, "note": { "type": "string" }, "expiry": { "type": "string", "default": "24h", "enum": [ "15m", "1h", "24h", "7d", "30d", "never" ] }, "redirect": { "type": "string" }, "external_reference": { "type": "string" } } } } } }, "responses": { "200": { "description": "{transaction_id, encrypted_id, url, amount, currency, cryptocurrency, expiry, status}" } } }, "get": { "tags": [ "Sell (402)" ], "summary": "List your one-off payment requests, or fetch one (?id=).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{payment_requests:[...]} | one request" } } } }, "/v1/challenge": { "post": { "tags": [ "Sell (402)" ], "summary": "Build the multi-coin 402 accepts[] for a resource {res_id}", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "res_id" ], "properties": { "res_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "{res_id, amount, currency, accepts:[...]}" } } } }, "/v1/verify": { "post": { "tags": [ "Buy" ], "summary": "Optional instant settle (POST the on-chain tx hash). Buyer-push: callable with just the challengeId (no key) after paying, OR with the seller X-Api-Key. The platform also auto-detects the on-chain payment.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verify" } } } }, "responses": { "200": { "description": "{settled:true} | {status:pending, confirmations, required} | {status:underpaid}" }, "404": { "description": "challenge not found" }, "410": { "description": "challenge expired" } } } }, "/v1/simulate-payment": { "post": { "tags": [ "Buy" ], "summary": "SANDBOX ONLY: advance a test-mode payment's simulated confirmations (no chain, no funds, no fees) and settle it at the threshold set at resource creation (test_confirmations, default 1). Works with the public challengeId alone (the hosted test page's Simulate payment button) or the seller key. A live resource is refused 403 uxc_not_sandbox.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId" ], "properties": { "challengeId": { "type": "string" }, "confirmations": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1 } } } } } }, "responses": { "200": { "description": "{settled:false, test:true, confirmations, minimum_confirmations, hash} | {settled:true, test:true, ...}" }, "403": { "description": "uxc_not_sandbox (not a test-mode resource) | uxc_publishable_key" }, "410": { "description": "challenge expired or already settled" } } } }, "/v1/sandbox-keys": { "get": { "tags": [ "Account" ], "summary": "List the account's self-provisioned sandbox (sk_test_/pk_test_) keys. Masked hints only; hashes never leave the registry. Also in the dashboard: Account > Sandbox.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{keys:[{id, kind, mode, label, key_hint, status, created_at, revoked_at, last_used_at}]}" } } }, "post": { "tags": [ "Account" ], "summary": "Create a sandbox key {kind: secret (sk_test_) | publishable (pk_test_), label?}. The raw key is returned EXACTLY ONCE (hash-at-rest afterwards). Test keys create test records only: no funds, no fees, excluded from live reporting. Throttled 10/hour. POST ?key_id=N&rotate=key rotates instead: fresh raw ONCE, old key stops working immediately.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "secret", "publishable" ], "default": "secret" }, "label": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "200": { "description": "{api_key (shown once), kind, key_hint}" } } }, "delete": { "tags": [ "Account" ], "summary": "Revoke a sandbox key ?key_id=N (401s immediately; never deleted - audit trail).", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "key_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{revoked:true, id}" }, "404": { "description": "sandbox key not found" } } } }, "/r/{id}": { "get": { "tags": [ "Buy" ], "summary": "The 402 door (back-compat alias of pay.u.cash /checkout/; same engine, same challenges - prefer the resource checkout_url). HTTP 402 + accepts[] (machine; + WWW-Authenticate: x402 + paymentRequirements[] when an exact entry is offered), a payable HTML page (browser), or 200 if settled. With an X-PAYMENT header it verifies + settles an exact (x402) payment and returns X-PAYMENT-RESPONSE. Public.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "402": { "description": "accepts[] + paymentRequirements[]" }, "200": { "description": "settled or the HTML page" }, "202": { "description": "exact payment verified, pending on-chain settlement" } } } }, "/v1/exact-verify": { "post": { "tags": [ "Buy" ], "summary": "x402 facilitator verify: is this signed EIP-3009 USDC-on-Base payment acceptable? Pure signature check, no settle.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "paymentPayload": { "type": "object" }, "paymentRequirements": { "type": "object", "description": "carries resource (the /r/{res_id} URL)" } } } } } }, "responses": { "200": { "description": "{isValid, invalidReason?, payer}" } } } }, "/v1/exact-settle": { "post": { "tags": [ "Buy" ], "summary": "x402 facilitator settle: verify the signed payment AND settle (relay by default; opt-out, or POST a tx hash, for verify-only).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "paymentPayload": { "type": "object" }, "paymentRequirements": { "type": "object" } } } } } }, "responses": { "200": { "description": "{success, transaction, network, payer, errorReason?}. Hard failures (bad signature, expiry, payee mismatch, no open challenge) ALSO return this shape with success:false + errorReason." } } } }, "/v1/exact-relay": { "post": { "tags": [ "Account" ], "summary": "Manage the exact relayer for instant, gasless USDC-on-Base settlement (ON by default, opt-out; seller billed gas + 21% per gasless settle). Writes (POST/DELETE) need the settings.edit capability for a subagent key.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "integer", "description": "1 = gasless (default), 0 = opt out (buyer-pays-gas)" }, "private_key": { "type": "string", "description": "ignored (relayer is platform-managed)" } } } } } }, "responses": { "200": { "description": "masked relay config" }, "403": { "description": "uxc_forbidden (subagent key without settings.edit)" } } } }, "/checkout-sessions": { "post": { "tags": [ "UCP" ], "summary": "Create a UCP checkout session (multi-item, mixed-currency cart). Merchant resolved from the host or ?cloud=.", "security": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "responses": { "200": { "description": "{id, status, currency, line_items, totals, ap2:{merchant_authorization, nonce}}" } } } }, "/checkout-sessions/{id}": { "get": { "tags": [ "UCP" ], "summary": "Fetch a checkout session (status: incomplete -> ready_for_complete -> completed)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cloud", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "the session" }, "404": { "description": "not found" } } } }, "/checkout-sessions/{id}/complete": { "post": { "tags": [ "UCP" ], "summary": "Mint payment challenges -> ready_for_complete. Optional AP2: {ap2:{checkout_mandate}} holder-proof (verified, else 401).", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ap2" } } } }, "responses": { "200": { "description": "ready_for_complete + payment_handlers[]" }, "401": { "description": "mandate_invalid_signature | mandate_expired | mandate_scope_mismatch" } } } }, "/checkout-sessions/{id}/cancel": { "post": { "tags": [ "UCP" ], "summary": "Cancel a checkout session", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "canceled" } } } }, "/orders/{id}": { "get": { "tags": [ "UCP" ], "summary": "A checkout session viewed as a UCP order (per-item fulfillment status)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{id, checkout_id, currency, line_items, fulfillment, totals}" }, "404": { "description": "not found" } } } }, "/catalog/search": { "post": { "tags": [ "UCP" ], "summary": "Search the merchant catalog (text + price filter + pagination)", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "filters": { "type": "object" }, "pagination": { "type": "object" } } } } } }, "responses": { "200": { "description": "{products[], pagination}" } } } }, "/catalog/lookup": { "post": { "tags": [ "UCP" ], "summary": "Batch catalog lookup by id", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "{products[]}" } } } }, "/catalog/product": { "post": { "tags": [ "UCP" ], "summary": "Fetch a single product by id", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "one product" }, "404": { "description": "uxc_not_found" } } } }, "/v1/account-info": { "get": { "tags": [ "Account" ], "summary": "Alias of /v1/agent (account snapshot).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "same as /v1/agent" } } } }, "/v1/transactions": { "get": { "tags": [ "Account" ], "summary": "Full transaction history with filters (type, status, asset, store_id, date range, search), pagination, ?transaction_id=N for one transaction, ?transaction_id=N&webhook_log=1 for its webhook deliveries, and ?download=1 (+any filters) for the CSV export.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{transactions:[...], pagination:{total,limit,offset}} | {transaction:{...}} | {webhook_log:[...]} | CSV bytes" } } }, "post": { "tags": [ "Account" ], "summary": "Per-transaction actions: ?transaction_id=N&action=refund (needs a refund-capable connected node/Stripe), action=resend-webhook (needs a webhook URL), action=submit-hash {hash} (attach the on-chain hash you paid with). Subagent store_scope is enforced.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "transaction_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "refund", "resend-webhook", "submit-hash" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string" } } } } } }, "responses": { "200": { "description": "{refunded:true} | {resent:true, webhook_response} | {submitted:true, tx_hash}" }, "400": { "description": "state guard errors (e.g. refunds-not-enabled, no webhook configured)" } } } }, "/v1/checkouts": { "get": { "tags": [ "Storefront" ], "summary": "List shop products (the checkout items a buyer sees), or fetch one (?checkout_id=N / slug).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{checkouts:[...]} | {checkout:{...}}" } } }, "post": { "tags": [ "Storefront" ], "summary": "Create a shop product: title, price, asset, description, etc. The buyer-facing checkout is born immediately. Optional Idempotency-Key header makes retried creates replay instead of duplicating.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "retry-safe create: the same key + body replays the original response (Idempotency-Replayed: true) instead of duplicating" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "price" ], "properties": { "title": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "asset": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "{checkout:{...}}" } } }, "put": { "tags": [ "Storefront" ], "summary": "Update a product (?checkout_id=N). Optimistic concurrency: send the version you read; a stale version is rejected.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "checkout_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{checkout:{...}}" }, "409": { "description": "version mismatch" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Delete a product (?checkout_id=N).", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "checkout_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted:true, id}" } } } }, "/v1/stores": { "get": { "tags": [ "Storefront" ], "summary": "List stores (multi-store). Subagents may list even without manage rights.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{stores:[...]}" } } }, "post": { "tags": [ "Storefront" ], "summary": "Create a store {label, webhook_url} -> returns its api_key + cloud_token + webhook_secret ONCE (write them down; keys are hash-at-rest and never shown again - the list exposes only the masked api_key_hint). POST ?store_id=N&rotate=api_key|webhook_secret|cloud_token rotates a credential (rotate=api_key returns the fresh raw key once); POST ?store_id=N&action=test-webhook fires a test delivery.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "webhook_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "{store:{...}} | {api_key, cloud_token, webhook_secret} | {test:{...}}" } } }, "put": { "tags": [ "Storefront" ], "summary": "Update a store (?store_id=N) label/webhook_url/status.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{store:{...}}" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Delete a store (?store_id=N). Owner-only.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted:true, id}" } } } }, "/v1/landers": { "get": { "tags": [ "Storefront" ], "summary": "List landing pages, fetch one (?lander_id=N), or its inbound offers (?lander_id=N&offers=1).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{landers:[...]} | {lander:{...}} | {offers:[...]}" } } }, "post": { "tags": [ "Storefront" ], "summary": "Turn an is_lander=1 checkout into a landing page {checkout_id, tpl?: spotlight}. Free-tier slot accounting applies (see /v1/billing); a pack adds slots.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout_id" ], "properties": { "checkout_id": { "type": "integer", "description": "a checkout created with is_lander=1 (POST /v1/checkouts)" }, "tpl": { "type": "string" } } } } } }, "responses": { "200": { "description": "{lander_id}" }, "402": { "description": "no-free-lander-slots (buy a pack via /v1/billing)" }, "404": { "description": "checkout is not a lander" } } }, "put": { "tags": [ "Storefront" ], "summary": "Update a lander (?lander_id=N), or set an offer status (?lander_id=N&offer_id=M&offer_status=new|viewed|accepted|rejected|spam).", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "lander_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{updated:true, id} | {updated:true, offer_id}" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Delete a lander (?lander_id=N); frees its slot.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "lander_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{deleted:true, id}" } } } }, "/v1/discount-codes": { "get": { "tags": [ "Storefront" ], "summary": "List discount codes (multiplier codes, e.g. 0.8 = 20% off).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{discount_codes:[...]}" } } }, "post": { "tags": [ "Storefront" ], "summary": "Add a code {code, multiplier, ...}.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "multiplier" ], "properties": { "code": { "type": "string" }, "multiplier": { "type": "number", "minimum": 0, "maximum": 1 } } } } } }, "responses": { "200": { "description": "{discount_codes:[...], added:{code}}" } } }, "put": { "tags": [ "Storefront" ], "summary": "Bulk-replace codes with an array body (import/export workflow).", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array" } } } } } }, "responses": { "200": { "description": "{discount_codes:[...], replaced:N}" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Remove a code (?code=).", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{removed, discount_codes}" } } } }, "/v1/custom-fields": { "get": { "tags": [ "Storefront" ], "summary": "List checkout custom form fields (text/checkbox/textarea/select).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{custom_fields:[...]}" } } }, "post": { "tags": [ "Storefront" ], "summary": "Add a custom field {type, label, options?, required?}.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "label" ], "properties": { "type": { "type": "string", "enum": [ "text", "checkbox", "textarea", "select" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{custom_fields:[...], added:true}" } } }, "delete": { "tags": [ "Storefront" ], "summary": "Remove a field (?index=N).", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "index", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{custom_fields:[...], removed_index}" } } } }, "/v1/payout-info": { "get": { "tags": [ "Account" ], "summary": "List payout-info requests (type-4: merchant-mediated fiat<->crypto/OTC payouts).", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{requests:[...]}" } } }, "post": { "tags": [ "Account" ], "summary": "Request payout info -> {transaction_id, link}. ?transaction_id=N&action=complete marks it completed.", "security": [ { "ApiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payout_asset": { "type": "string" }, "details": { "type": "string" } } } } } }, "responses": { "200": { "description": "{transaction_id, link} | {completed:true, id}" } } } }, "/v1/billing": { "get": { "tags": [ "Account" ], "summary": "Balances + lander slot pack status: {credit_balance, ucash_points, lander_slots}.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{credit_balance, ucash_points, lander_slots:{...}}" } } }, "post": { "tags": [ "Account" ], "summary": "Actions: {action:\"buy-lander-pack\", qty} (debits credit) or {action:\"redeem-ucash\", amount} (converts UCASH points to platform credit).", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "buy-lander-pack", "redeem-ucash" ] }, "qty": { "type": "integer" }, "amount": { "type": "number" } } } } } }, "responses": { "200": { "description": "the updated balances" }, "402": { "description": "uxc_insufficient_balance" } } } }, "/relayer/{id}": { "get": { "tags": [ "Buy" ], "summary": "Public: is this resource sponsored by a gasless relayer? Returns the relayer address + its Base ETH balance (buyers pay zero gas when funded). Also the human-facing /fund-relayer page target.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{res_id, configured, active, funding, funded_address, balance, network, pay_to}" }, "404": { "description": "resource not found" } } } }, "/v1/prime/link": { "post": { "tags": [ "Prime" ], "summary": "Claim a member's one-time prime link code (minted at prime.u.cash/agents-link) and bind this agent to their Univirse. Scopes and UNITS/day spend ceilings are member-set.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "the pl-... one-time code" } } } } } }, "responses": { "200": { "description": "{link_id, consumer_id, scopes:[...]}" }, "404": { "description": "no such code" }, "409": { "description": "code already claimed/revoked" }, "410": { "description": "code expired" } } } }, "/v1/prime/me": { "get": { "tags": [ "Prime" ], "summary": "The linked member summary: memberships, highest tier, champion roster. Scope prime.read.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{link_id, consumer_id, scopes, memberships, highest_tier, champions, roster, since}" }, "403": { "description": "no active link or missing scope" } } } }, "/v1/prime/characters": { "get": { "tags": [ "Prime" ], "summary": "Full champion sheets of the linked member: stats, skills, chronicle, location, training. Scope prime.characters.read.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{count, characters:[...]}" } } } }, "/v1/prime/character": { "get": { "tags": [ "Prime" ], "summary": "One full champion sheet (?id=N, must belong to the linked member). Scope prime.characters.read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "the champion sheet" }, "404": { "description": "not on this link" } } } }, "/v1/prime/act": { "post": { "tags": [ "Prime" ], "summary": "Act for the linked member: {action: train|travel|mission-start|mission-claim, character_id?, stat?, galaxy?, mission_id?, run_id?}. Scope prime.characters.act.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "train", "travel", "mission-start", "mission-claim" ] }, "character_id": { "type": "integer" }, "stat": { "type": "string" }, "galaxy": { "type": "string" }, "mission_id": { "type": "integer" }, "run_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "action result" }, "402": { "description": "insufficient training points" }, "403": { "description": "scope missing or champion not on this link" } } } }, "/v1/prime/explore": { "get": { "tags": [ "Prime" ], "summary": "The Atlas catalog: nodes (galaxy, danger, caps), the member fragments, progress, and any scanning visit. Scope prime.read.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{nodes:[...], fragments:[...], progress, scanning:[...]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Atlas actions: {action: scan|claim, slug?, character_id?}. Scans are galaxy-gated by the champion location; claims pay UNITS through the pool and roll a lore fragment. Scope prime.explore.act.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "scan", "claim" ] }, "slug": { "type": "string" }, "character_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{scan_sec} | the claim find" } } } }, "/v1/prime/games": { "get": { "tags": [ "Prime" ], "summary": "The trial catalog with ceilings, caps, and the member standing (pick slugs here). Scope prime.read.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{games:[{slug, kind, max_plausible, plays_per_day, my_best, ...}]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Arcade trials through the member pipeline: {action: start|finish, slug, character_id?, token?, events?}. Server-authoritative scoring; rewards settle like a member play. Scope prime.games.act.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "start", "finish" ] }, "slug": { "type": "string" }, "token": { "type": "string" }, "events": { "type": "array" } } } } } }, "responses": { "200": { "description": "{token, rounds} | {score, rewards}" } } } }, "/v1/prime/studio": { "get": { "tags": [ "Prime" ], "summary": "The linked member's Forge jobs.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{jobs:[...]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Forge media: {action: quote|order, slug, quote?, opts?, character_id?}. Orders are bounded by the member's UNITS/day grant (402 grant-ceiling) and the single qid-bound charge. Scope prime.studio.spend.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "slug" ], "properties": { "action": { "type": "string", "enum": [ "quote", "order" ] }, "slug": { "type": "string" }, "quote": { "type": "string" }, "opts": { "type": "object" }, "character_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{price_units, quote} | {jti, state}" }, "402": { "description": "grant-ceiling or insufficient" } } } }, "/v1/prime/inventions": { "get": { "tags": [ "Prime" ], "summary": "The linked member's inventions.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{inventions:[...]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Propose an invention: 2+ owned lore fragments + 1+ learned skill + a thesis. AI canon review runs server-side; the operator publishes or rejects. Scope prime.inventions.propose.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "thesis", "fragment_ids", "skills" ], "properties": { "name": { "type": "string" }, "thesis": { "type": "string" }, "character_id": { "type": "integer" }, "fragment_ids": { "type": "array", "items": { "type": "integer" } }, "skills": { "type": "array", "items": { "type": "string" } } } } } }, "responses": { "200": { "description": "{invention_id, review:{verdict,...}}" } } } } }, "/v1/prime/pvp": { "get": { "tags": [ "Prime" ], "summary": "The Crucible ladder and the duels involving the linked member. Scope prime.pvp.act.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{ladder:[...], challenges:[...]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Duels: {action: create|accept|decline|cancel, defender_character_id?, wager_units?, challenge_id?}. Accept resolves the defender from the CALLER'S OWN link (an agent can never accept a duel aimed at a member who never consented). Wagers burn the fail-closed prime.pvp.wager UNITS/day grant (402 wager-grant-ceiling). Scope prime.pvp.act.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "create", "accept", "decline", "cancel" ] }, "defender_character_id": { "type": "integer" }, "wager_units": { "type": "integer" }, "challenge_id": { "type": "integer" }, "character_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{challenge_id, ...} | the resolved duel" }, "402": { "description": "wager-grant-ceiling" }, "403": { "description": "not-your-duel (defender law)" } } } }, "/v1/prime/tournaments": { "get": { "tags": [ "Prime" ], "summary": "Open arcade heats with live boards and the member entry state. Scope prime.tournaments.act.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{tournaments:[{slug, game, entry_units, board:[...]}]}" } } }, "post": { "tags": [ "Prime" ], "summary": "Enter a heat: {action: enter, slug}. The UNITS entry burns the fail-closed prime.tournament.entry grant before the escrow hold. Scope prime.tournaments.act.", "security": [ { "ApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "slug" ], "properties": { "action": { "type": "string", "enum": [ "enter" ] }, "slug": { "type": "string" }, "character_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{escrow_id, entry_units}" }, "402": { "description": "entry-grant-ceiling" } } } }, "/v1/prime/quests": { "get": { "tags": [ "Prime" ], "summary": "The quest board, streaks, and the running season, recomputed live. Claims stay member-only (a claim is member intent; agents generate the progress). Scope prime.read.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "{quests:[...], streaks:{...}, season:{...}}" } } } }, "/v1/prime/feed": { "get": { "tags": [ "Prime" ], "summary": "The activity feed: everything this link agent did (?since_id=&limit=), one journal row per successful action. Scope prime.feed.read.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "since_id", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{events:[...], last_id}" } } } } } }