{"openapi":"3.1.0","info":{"title":"Catena Agent API","description":"Agent-facing API consumed by the MCP server and catena-cli on behalf of agents. GENERATED from the valibot schemas in routes/v1/agent-api.ts, filtered to production-supported networks, by src/openapi/agent-api-document.ts — do not edit by hand. Served live at GET /v1/agent-api/openapi.json; oasdiff (pnpm run openapi:compat) guards the committed copy for backward compatibility.","version":"1.0.0"},"servers":[{"url":"/v1/agent-api"}],"tags":[{"name":"auth"},{"name":"agent"},{"name":"counterparties"},{"name":"networks"},{"name":"intents"},{"name":"evidence"}],"paths":{"/claim":{"post":{"tags":["auth"],"summary":"Claim a provisioned agent and mint its first session","security":[{"operatorBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"clientInstanceId":{"type":"string","minLength":1},"clientLabel":{"type":"string","minLength":1}},"required":["agentId","clientInstanceId"]}}}},"responses":{"200":{"description":"Agent claimed; session and refresh tokens minted","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"organizationId":{"type":"string"},"sessionToken":{"type":"string"},"refreshToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"apiKey":{"type":"string"},"name":{"type":"string"},"activated":{"type":"boolean"},"policy":{"anyOf":[{"type":"object","properties":{},"required":[]},{"type":"null"}]},"policyError":{"anyOf":[{"type":"string"},{"type":"null"}]},"accounts":{"type":"array","items":{"type":"object","properties":{},"required":[]}},"accountsError":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["agentId","organizationId","sessionToken","refreshToken","expiresAt","apiKey","name","activated","policy","policyError","accounts","accountsError"]}}}},"401":{"description":"Operator authentication missing a user id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Token not issued to an agent-linking OAuth client, or agent provisioned for a different operator","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Agent already claimed or not in a claimable state","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/refresh":{"post":{"tags":["auth"],"summary":"Rotate a refresh token for a new session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","minLength":1}},"required":["refreshToken"]}}}},"responses":{"200":{"description":"New session and refresh tokens minted","content":{"application/json":{"schema":{"type":"object","properties":{"sessionToken":{"type":"string"},"refreshToken":{"type":"string"},"apiKey":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionToken","refreshToken","apiKey","expiresAt"]}}}},"401":{"description":"Unknown, revoked, or expired refresh token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Agent revoked, suspended, or inactive","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/unlink":{"post":{"tags":["auth"],"summary":"Unlink the current agent client context","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Client context unlinked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"enum":[true]}},"required":["success"]}}}},"401":{"description":"Session token missing, unknown, or expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Client unlinked or agent inactive","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/signer/register":{"post":{"tags":["auth"],"summary":"Register the agent client's signing public key","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"algorithm":{"enum":["p256"]},"publicKeyHex":{"type":"string","pattern":"^0[23][0-9a-f]{64}$"}},"required":["algorithm","publicKeyHex"]}},"required":["signer"]}}}},"responses":{"200":{"description":"Signer registration state","content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"status":{"enum":["registered","already_registered","not_applicable","registration_failed"],"type":"string"},"publicKeyHex":{"type":"string","pattern":"^0[23][0-9a-f]{64}$"},"reason":{"type":"string"}},"required":["status"]}},"required":["signer"]}}}},"401":{"description":"Session token missing, unknown, or expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Client unlinked or agent inactive","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Agent already has a different signer","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"422":{"description":"Agent already holds as many signing keys as the signing provider allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/me":{"get":{"tags":["agent"],"summary":"Resolve the agent behind the session token","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Agent identity","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["pending_claim","active","suspended","pending_policy","revoked"],"type":"string"},"organizationId":{"type":"string"}},"required":["id","name","status","organizationId"]}},"required":["agent"]}}}}}}},"/policy":{"get":{"tags":["agent"],"summary":"Get the policy assigned to the agent","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Assigned policy","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"accountAccess":{"anyOf":[{"type":"object","properties":{"read":{"type":"array","items":{"type":"string"}},"send":{"type":"array","items":{"type":"string"}},"transfer":{"type":"array","items":{"type":"string"}}},"required":["read","send","transfer"]},{"type":"null"}],"description":"Accounts the policy permits for each capability; null when the policy is invalid"},"rules":{"anyOf":[{"type":"object","properties":{"send":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique within the policy. An all-account rule's id is its stored rule id. A one-account rule's id adds the capability and account to its stored rule id, so it does not match the policyCapabilities rule id"},"scope":{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string"}},"required":["type","accountId"]}]},"counterparties":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"enum":["counterparty"]},"counterpartyId":{"type":"string"}},"required":["type","counterpartyId"]}]}},"required":["accounts","counterparties"]},"limit":{"oneOf":[{"type":"object","properties":{"type":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"threshold":{"type":"object","properties":{"amount":{"type":"string","description":"Decimal amount string"},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]}},"required":["type","threshold"]},{"type":"object","properties":{"type":{"enum":["hourly_count","daily_count"],"type":"string"},"threshold":{"type":"number"}},"required":["type","threshold"]}]},"action":{"oneOf":[{"type":"object","properties":{"type":{"enum":["block"]}},"required":["type"]},{"type":"object","properties":{"type":{"enum":["require_approval"]},"requiredApprovals":{"type":"number"}},"required":["type","requiredApprovals"]}]}},"required":["id","scope","limit","action"]}},"transfer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique within the policy. An all-account rule's id is its stored rule id. A one-account rule's id adds the capability and account to its stored rule id, so it does not match the policyCapabilities rule id"},"scope":{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string"}},"required":["type","accountId"]}]}},"required":["accounts"]},"limit":{"oneOf":[{"type":"object","properties":{"type":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"threshold":{"type":"object","properties":{"amount":{"type":"string","description":"Decimal amount string"},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]}},"required":["type","threshold"]},{"type":"object","properties":{"type":{"enum":["hourly_count","daily_count"],"type":"string"},"threshold":{"type":"number"}},"required":["type","threshold"]}]},"action":{"oneOf":[{"type":"object","properties":{"type":{"enum":["block"]}},"required":["type"]},{"type":"object","properties":{"type":{"enum":["require_approval"]},"requiredApprovals":{"type":"number"}},"required":["type","requiredApprovals"]}]}},"required":["id","scope","limit","action"]}}},"required":["send","transfer"]},{"type":"null"}],"description":"Every rule that limits sends and transfers, each scoped to one account or to all of the capability's accounts together; null when the policy is invalid"},"invalidReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the stored policy cannot be read as account access and scoped rules; null when it can"},"version":{"type":"number"},"kind":{"enum":["base","override"],"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"evidenceRequirements":{"type":"object","properties":{"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"instructions":{"type":"string"},"accepts":{"type":"array","items":{"type":"string"},"description":"The forms that satisfy the field; a value in any one of them does"}},"required":["label","accepts"]},"description":"Each evidence field the policy defines, by field key"},"requiredByCapability":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}},"description":"The field keys an intent under each capability must carry, in order. send also covers x402 and mpp actions. A capability left out needs no evidence"}},"required":["fields","requiredByCapability"],"description":"The evidence the policy requires with each capability's intents, sent as `evidence` on POST /intents. Absent when the policy requires none"}},"required":["id","name","description","capabilities","accountAccess","rules","invalidReason","version","kind"]}},"required":["policy"]}}}},"404":{"description":"No policy assigned","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/setup-state":{"get":{"tags":["agent"],"summary":"Report the agent's onboarding readiness and blocking steps","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Setup state: agent status, organization gates, policy assignment, account access and funding, signer registration, and the ordered setup steps with the capability each one still gates. A missing policy is reported as state, never as an error.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["pending_claim","active","suspended","pending_policy","revoked"],"type":"string"}},"required":["id","name","status"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"environment":{"enum":["live","sandbox"],"type":"string"},"kybVerified":{"type":"boolean","description":"Organization completed account verification, which is what opens the fiat rails"},"onboarding":{"type":"object","properties":{"postSignupRequired":{"type":"boolean"},"organizationNameRequired":{"type":"boolean"},"nonCustodialTermsRequired":{"type":"boolean"},"nonCustodialWalletSecurityRequired":{"type":"boolean"}},"required":["postSignupRequired","organizationNameRequired","nonCustodialTermsRequired","nonCustodialWalletSecurityRequired"]},"capabilities":{"type":"object","properties":{"fiat-rails":{"type":"boolean"},"onchain:base":{"type":"boolean"},"onchain:base-sepolia":{"type":"boolean"},"onchain:arc":{"enum":[true]},"onchain:arc-testnet":{"enum":[true]},"kyb":{"type":"boolean"}},"required":["fiat-rails","onchain:base","onchain:base-sepolia","kyb"]},"heldAssets":{"type":"array","items":{"type":"string"},"description":"Additional assets enabled for this organization. Empty when USDC alone is available"},"closedNetworks":{"type":"array","items":{"type":"string"},"description":"The networks Catena has made temporarily unavailable among those this agent may use and the chains its custodial accounts hold their money on. They refuse new payments with onchain_network_closed, and money on them does not count toward accounts.hasFundedAccount. Money already on them is safe, and payments already in progress complete"}},"required":["id","environment","kybVerified","onboarding","capabilities","heldAssets","closedNetworks"]},"policy":{"type":"object","properties":{"assigned":{"type":"boolean"},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["assigned"]},"accounts":{"type":"object","properties":{"accessibleCount":{"type":"number"},"hasFundedAccount":{"type":"boolean","description":"At least one readable account has positive available USD at par across assets this organization holds, on networks the agent may use. Closed networks, inactive accounts and retired wallets do not count."}},"required":["accessibleCount","hasFundedAccount"]},"signer":{"type":"object","properties":{"registered":{"type":"boolean"}},"required":["registered"]},"ready":{"type":"boolean","description":"Agent is active with a policy and at least one accessible account, so it can act at all. Steps can still be required alongside it; each gates only the capability it names"},"steps":{"type":"array","items":{"type":"object","properties":{"key":{"enum":["claim_agent","organization_onboarding","kyb_verification","assign_policy","fund_account","register_signer"],"type":"string"},"status":{"enum":["complete","required","not_applicable"],"type":"string","description":"Whether this step is done, still outstanding, or not needed here. A required step gates the capability it names, which is often narrower than everything the agent can do"},"actor":{"enum":["operator","agent"],"type":"string","description":"Who can complete this step"},"requiredPermission":{"type":"string","description":"Operator permission that authorizes completing the step"},"hint":{"type":"string","description":"Plain-English instruction, surfaceable as-is"}},"required":["key","status","actor","hint"]}}},"required":["agent","organization","policy","accounts","signer","ready","steps"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/accounts":{"get":{"tags":["agent"],"summary":"List accounts the agent can act on under its policy","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Accessible accounts","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^acct_[0-9A-HJKMNP-TV-Z]{26}$"},"name":{"type":"string"},"type":{"type":"string"},"currency":{"type":"string"}},"required":["id","name","type","currency"]}}},"required":["accounts"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/accounts/{id}/balance":{"get":{"tags":["agent"],"summary":"Get a policy-gated account balance","security":[{"agentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Account balance in USD at par across assets, with an optional breakdown by network and token","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acct_[0-9A-HJKMNP-TV-Z]{26}$"},"balance":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Deprecated alias of balances.total: USD at par across assets"},"balances":{"type":"object","properties":{"total":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"USD at par across assets on every account network, including networks this agent may not use"},"available":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Aggregate unreserved funds in USD at par across assets on the networks this agent may use, leaving out a network Catena has closed. For a network-split account, this equals the sum of byNetwork available values. It describes the account and does not determine whether a particular payment can be funded. Zero while the account is not active, and zero when no network the account holds is open to agents."},"byNetwork":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"status":{"type":"string","description":"open while agents can spend on this network. closed while Catena has made the network temporarily unavailable: available is zero, total still counts the money there, which is safe, and payments already in progress complete. Treat any value other than open as a network you cannot spend on now"},"total":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"USD at par across assets on this network"},"available":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"]}},"required":["network","status","total","available"]},"description":"One entry for each network that the account holds and agents may use. Their available values add up to balances.available. Their total values can add up to less than balances.total, which also counts a network agents may not use. Every available is zero while the account is not active. A network Catena has closed keeps its entry, with status closed and available zero. An empty array means no network the account holds is open to agents. Absent until the account's money is split by network."},"holdings":{"type":"array","items":{"type":"object","properties":{"token":{"type":"string","description":"The token's CAIP-19 asset identifier"},"network":{"type":"string"},"networkLabel":{"type":"string"},"asset":{"type":"string"},"assetLabel":{"type":"string"},"total":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"]},"available":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"]}},"required":["token","network","networkLabel","asset","assetLabel","total","available"]},"description":"Optional breakdown by network and token, in USD at par across assets. When absent, every figure is USDC. Omitted for bank accounts and until the account's money is split by network. Only networks this agent may use are included. Available values sum to balances.available; total values sum to balances.total only when every account network is inside the agent network fence. Closed networks and inactive accounts have zero available, and retired wallets contribute to total alone."}},"required":["total","available"]}},"required":["accountId","balance","balances"]}}}},"403":{"description":"Account not accessible under this policy","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Readable account not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/accounts/{id}/transactions":{"get":{"tags":["agent"],"summary":"Get a policy-gated account transaction history","security":[{"agentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"end","in":"query","required":false,"description":"Inclusive upper bound; must be on or after `start` when both are provided","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Account transaction history","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acct_[0-9A-HJKMNP-TV-Z]{26}$"},"transactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["operator-send","operator-transfer","operator-deposit","operator-refund","microdeposit"],"type":"string"},"action":{"type":"string"},"status":{"enum":["pending","processing","completed","failed","reversed"],"type":"string"},"movementStatus":{"enum":["initiated","provider_pending","processing","completed","failed","reversed","manual_review"],"type":"string"},"direction":{"enum":["incoming","outgoing"],"type":"string"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"USD amount. With tokenDetails, the settled recipient credit, or zero for a movement within the same account. Otherwise the recorded transaction amount."},"fee":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"With tokenDetails, the net account debit beyond amount, in USD at par, including fees, conversion cost and customer-paid gas. A negative value is a net conversion credit. Otherwise the recorded Catena fee."},"tokenDetails":{"type":"object","properties":{"debited":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string","description":"Token symbol in the same lower-case vocabulary as balance holdings.asset"},"network":{"type":"string","description":"Network on which the token left or arrived"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Net quantity of this token on this network, valued in USD at par"}},"required":["asset","network","amount"]},"description":"Tokens netted out of the viewed account, one entry per token and network"},"credited":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string","description":"Token symbol in the same lower-case vocabulary as balance holdings.asset"},"network":{"type":"string","description":"Network on which the token left or arrived"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Net quantity of this token on this network, valued in USD at par"}},"required":["asset","network","amount"]},"description":"Tokens netted into the viewed account, including conversion surplus, one entry per token and network"},"paid":{"type":"string","description":"Destination token symbol, only when a payment converted a different funding token"}},"required":["debited","credited"],"description":"Optional settled token detail for this account. Primary amounts are USD at par; balance holdings use the same asset vocabulary. Omitted when token provenance is unavailable or the organization has no held-asset entitlement."},"currency":{"type":"string"},"network":{"type":"string"},"counterpartyName":{"type":"string"},"method":{"enum":["ach","wire","on-chain"],"type":"string"},"memo":{"type":"string"},"description":{"type":"string"},"txHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["id","type","action","status","movementStatus","direction","amount","fee","currency","createdAt"]}},"total":{"type":"number"}},"required":["accountId","transactions","total"]}}}},"403":{"description":"Account not accessible under this policy","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Readable account not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/accounts/{id}/deposit-address":{"get":{"tags":["agent"],"summary":"Get a policy-gated account deposit address","security":[{"agentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"network","in":"query","required":true,"schema":{"type":"string","enum":["base","arc"]}},{"name":"asset","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Account deposit address","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acct_[0-9A-HJKMNP-TV-Z]{26}$"},"address":{"type":"string"},"liquidationAddressId":{"type":"string"},"source":{"enum":["wallet","liquidation"],"type":"string"}},"required":["accountId","address","source"]}}}},"400":{"description":"Missing or unsupported network or asset","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Account not accessible under this policy","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Readable account not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Catena has closed the network to new work (`onchain_network_closed`), including addresses already issued on it. The closure has no known end and sends no `Retry-After`: do not retry on this network. `details.network` names it, and `details.alternatives` lists the account's open networks to ask for instead, empty when there are none. Also refused when the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"503":{"description":"Banking services are temporarily unavailable (`temporarily_unavailable`, with the service in `details`), or the banking provider did not answer (`temporarily_unavailable` without `details`). An address already created is still returned; send the request again after the `Retry-After` seconds","headers":{"Retry-After":{"description":"Seconds to wait before sending the request again. Sent with `temporarily_unavailable`","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/counterparties":{"get":{"tags":["counterparties"],"summary":"List counterparties visible to the agent","security":[{"agentBearer":[]}],"parameters":[{"name":"address","in":"query","required":false,"description":"Only counterparties with a wallet rail at this address; bank rails never match","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"network","in":"query","required":false,"description":"Only counterparties owning a wallet address in this network class; a matching rail can omit network when its configured destination is unavailable to the agent; such a rail cannot receive an agent send until that configuration or the organization's capability changes; bank rails never match","schema":{"type":"string","enum":["base","arc"]}}],"responses":{"200":{"description":"Visible counterparties","content":{"application/json":{"schema":{"type":"object","properties":{"counterparties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"enum":["ready","awaiting_details"],"type":"string"},"rails":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["bank","wallet"],"type":"string"},"walletAddress":{"type":"string"},"network":{"enum":["base","arc"],"type":"string"},"asset":{"type":"string"},"bankName":{"type":"string"},"accountNumber":{"type":"string"}},"required":["id","type"]}}},"required":["id","name","status","rails"]}}},"required":["counterparties"]}}}},"400":{"description":"Malformed address, unknown network, or network not enabled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/onchain-networks":{"get":{"tags":["networks"],"summary":"List the onchain networks enabled for this environment","security":[{"agentBearer":[]}],"responses":{"200":{"description":"Enabled onchain network ids, and those of them Catena has made temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"networks":{"type":"array","items":{"enum":["base","arc"],"type":"string"}},"closedNetworks":{"type":"array","items":{"enum":["base","arc"],"type":"string"},"description":"The networks in networks that Catena has made temporarily unavailable. They refuse new payments with onchain_network_closed; money already on them is safe, and payments already in progress complete. Use another network meanwhile"}},"required":["networks","closedNetworks"]}}}},"401":{"description":"Session token missing, unknown, or expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/intents":{"get":{"tags":["intents"],"summary":"List intents created by the authenticated agent","security":[{"agentBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Public intent statuses to include. Repeat to include any of several statuses; omit to include every status.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["pending","processing","completed","blocked","failed"]}}},{"name":"type","in":"query","required":false,"description":"Intent types to include. Repeat to include any of several types; omit to include every type.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"]}}},{"name":"start","in":"query","required":false,"description":"Inclusive lower bound on the intent creation time","schema":{"type":"string","format":"date-time"}},{"name":"accountId","in":"query","required":false,"description":"Resolved source account id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum intents to return","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of matching intents to skip","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Stored intent summaries for this durable agent identity in its organization, newest first. Use GET /intents/{id} for the full intent-specific result.","content":{"application/json":{"schema":{"type":"object","properties":{"intents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^int_[0-9A-HJKMNP-TV-Z]{26}$"},"accountId":{"type":"string"},"destinationAccountId":{"type":"string"},"type":{"enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"],"type":"string"},"status":{"enum":["pending","processing","completed","blocked","failed"],"type":"string"},"resolution":{"anyOf":[{"anyOf":[{"enum":["completed","blocked","denied","expired","failed","cancelled"],"type":"string"},{"type":"string","pattern":"\\S"}]},{"type":"null"}],"description":"Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings."},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"]},"counterpartyId":{"type":"string"},"counterpartyName":{"type":"string"},"network":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","properties":{"dataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataUrl"]},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"contentType":{"type":"string","description":"The media type verified from the file's bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name the agent gave the file, if any"}},"required":["contentType","sizeBytes","sha256Hex","filename"]}]},"description":"The evidence submitted with the intent, keyed by field key: text exactly as sent, or a file's details. Absent when the intent carries none"}},"required":["id","type","status","resolution","reasons","expiresAt","createdAt","metadata"]}},"total":{"type":"number"}},"required":["intents","total"]}}}},"400":{"description":"Invalid status, type, timestamp, account id, or pagination","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}},"post":{"tags":["intents"],"summary":"Create an intent for a governed action","security":[{"agentBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional operation identifier. Reuse the same value only when retrying the same logical submission. Without it, each request is a new submission with no request-idempotency guarantee. Separate x402/MPP approval correlation and nonce-reuse rules still apply.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"oneOf":[{"oneOf":[{"type":"object","properties":{"type":{"enum":["send"]},"accountId":{"type":"string","minLength":1},"counterpartyRailId":{"type":"string","minLength":1},"amount":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]},"description":{"type":"string","maxLength":280,"description":"Internal note stored in Catena"},"method":{"enum":["ach"]},"memo":{"type":"string","pattern":"^[A-Za-z0-9 ]{0,10}$","description":"Reference sent with the ACH payment. When the organization has set a default ACH memo, that memo is sent instead."}},"required":["type","counterpartyRailId","amount","method"]},{"type":"object","properties":{"type":{"enum":["send"]},"accountId":{"type":"string","minLength":1},"counterpartyRailId":{"type":"string","minLength":1},"amount":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]},"description":{"type":"string","maxLength":280,"description":"Internal note stored in Catena"},"method":{"enum":["wire"]},"memo":{"type":"string","maxLength":280,"description":"Reference sent with the wire payment"}},"required":["type","counterpartyRailId","amount","method"]},{"type":"object","properties":{"type":{"enum":["send"]},"accountId":{"type":"string","minLength":1},"counterpartyRailId":{"type":"string","minLength":1},"amount":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]},"description":{"type":"string","maxLength":280,"description":"Internal note stored in Catena"},"method":{"enum":["on-chain"]},"memo":{"type":"string","maxLength":280,"description":"Deprecated for on-chain sends and not sent to the blockchain; use description for an internal note","deprecated":true}},"required":["type","counterpartyRailId","amount","method"]}],"description":"For sends, accountId may be omitted when the agent's current effective policy allows sends from exactly one account. The resolved source is pinned to the intent; zero or multiple send accounts are rejected.","type":"object"},{"type":"object","properties":{"type":{"enum":["transfer"]},"accountId":{"type":"string","minLength":1},"toAccountId":{"type":"string","minLength":1},"amount":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"]},"memo":{"type":"string","maxLength":280},"description":{"type":"string","maxLength":280}},"required":["type","accountId","toAccountId","amount"]},{"type":"object","properties":{"type":{"enum":["create_counterparty"]},"name":{"type":"string","minLength":1,"maxLength":40},"email":{"type":"string","format":"email"},"rail":{"oneOf":[{"type":"object","properties":{"type":{"enum":["bank"]},"bankName":{"type":"string","minLength":1},"routingNumber":{"type":"string","pattern":"^\\d{9}$"},"accountNumber":{"type":"string","pattern":"^\\d{4,17}$"},"accountType":{"enum":["checking","savings"],"type":"string"},"address":{"type":"string"},"addressStreet":{"type":"string","minLength":3,"maxLength":35},"addressCity":{"type":"string","minLength":1},"addressState":{"type":"string"},"addressPostalCode":{"type":"string"},"addressCountry":{"type":"string"}},"required":["type","bankName","routingNumber","accountNumber","addressStreet","addressCity","addressState","addressPostalCode"]},{"type":"object","properties":{"type":{"enum":["wallet"]},"walletAddress":{"type":"string","minLength":1},"network":{"enum":["base","arc"],"type":"string"},"disabledNetworks":{"type":"array","items":{"enum":["base","arc"],"type":"string"}},"asset":{"type":"string"}},"required":["type","walletAddress","network"]}]}},"required":["type","name"],"description":"A counterparty requires either payment rail details or a contact email.","anyOf":[{"required":["rail"]},{"required":["email"]}]},{"type":"object","properties":{"type":{"enum":["request_counterparty_details"]},"counterpartyId":{"type":"string","minLength":1},"methods":{"type":"object","properties":{"bank":{"type":"boolean"},"wallet":{"type":"boolean"}},"required":["bank","wallet"]}},"required":["type","counterpartyId","methods"]},{"type":"object","properties":{"type":{"enum":["x402"]},"accountId":{"type":"string","minLength":1},"paymentRequirements":{"type":"object","properties":{"scheme":{"type":"string","maxLength":64},"network":{},"asset":{"type":"string","maxLength":128},"amount":{"type":"string","pattern":"^\\d+$","maxLength":78},"payTo":{"type":"string","maxLength":128},"maxTimeoutSeconds":{"type":"integer","minimum":1},"extra":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]},"resource":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"description":{"type":"string","maxLength":1024},"mimeType":{"type":"string","maxLength":255},"serviceName":{"type":"string","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":64}},"iconUrl":{"type":"string","maxLength":2048}},"required":["url"]},"authorization":{"type":"object","properties":{"from":{"type":"string","maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"A 20-byte hex address, either all-lowercase or spelled with a valid EIP-55 checksum."},"to":{"type":"string","maxLength":42,"pattern":"^0x[0-9a-fA-F]{40}$","description":"A 20-byte hex address, either all-lowercase or spelled with a valid EIP-55 checksum."},"value":{"type":"string","maxLength":78,"pattern":"^(0|[1-9]\\d*)$"},"validAfter":{"type":"string","maxLength":78,"pattern":"^(0|[1-9]\\d*)$"},"validBefore":{"type":"string","maxLength":78,"pattern":"^(0|[1-9]\\d*)$"},"nonce":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["from","to","value","validAfter","validBefore","nonce"]},"signedOffer":{"oneOf":[{"type":"object","properties":{"format":{"enum":["eip712"]},"acceptIndex":{"type":"integer","minimum":0},"payload":{"type":"object","properties":{"version":{"enum":[1]},"resourceUrl":{"type":"string","maxLength":2048},"scheme":{"type":"string","maxLength":64},"network":{"type":"string","maxLength":64},"asset":{"type":"string","maxLength":128},"payTo":{"type":"string","maxLength":128},"amount":{"type":"string","pattern":"^\\d+$","maxLength":78},"validUntil":{"type":"integer","minimum":0}},"required":["version","resourceUrl","scheme","network","asset","payTo","amount"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["format","payload","signature"]},{"type":"object","properties":{"format":{"enum":["jws"]},"acceptIndex":{"type":"integer","minimum":0},"signature":{"type":"string","maxLength":8192,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$"}},"required":["format","signature"]}]}},"required":["type","accountId","paymentRequirements"]},{"type":"object","properties":{"type":{"enum":["mpp"]},"accountId":{"type":"string","minLength":1},"challenge":{},"resource":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"serviceName":{"type":"string","maxLength":255}},"required":["url"]}},"required":["type","accountId","challenge"]},{"type":"object","properties":{"type":{"enum":["policy_override"]},"schemaVersion":{"enum":[1]},"operations":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"enum":["increase_limit"]},"accountId":{"type":"string","minLength":1},"capability":{"enum":["send","transfer"],"type":"string"},"counterpartyId":{"type":"string","minLength":1},"limitType":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"newLimit":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"],"additionalProperties":false}},"required":["type","accountId","capability","limitType","newLimit"],"additionalProperties":false,"title":"PolicyOverrideAmountLimitOperation"},{"type":"object","properties":{"type":{"enum":["increase_limit"]},"accountId":{"type":"string","minLength":1},"capability":{"enum":["send","transfer"],"type":"string"},"counterpartyId":{"type":"string","minLength":1},"limitType":{"enum":["hourly_count","daily_count"],"type":"string"},"newLimit":{"type":"object","properties":{"count":{"type":"integer","minimum":1}},"required":["count"],"additionalProperties":false}},"required":["type","accountId","capability","limitType","newLimit"],"additionalProperties":false,"title":"PolicyOverrideCountLimitOperation"}]},"minItems":1,"maxItems":10},"durationSeconds":{"type":"integer","minimum":60,"maximum":604800},"reason":{"type":"string","minLength":1,"maxLength":280}},"required":["type","schemaVersion","operations","durationSeconds","reason"]},{"type":"object","properties":{"type":{"enum":["policy_override"]},"schemaVersion":{"enum":[2]},"operations":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"enum":["increase_limit"]},"capability":{"enum":["send","transfer"],"type":"string"},"limitType":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"scope":{"anyOf":[{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]},"counterparties":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["counterparty"]},"counterpartyId":{"type":"string","minLength":1}},"required":["type","counterpartyId"],"additionalProperties":false}]}},"required":["accounts","counterparties"],"additionalProperties":false,"title":"PolicyOverrideSendScope"},{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]}},"required":["accounts"],"additionalProperties":false,"title":"PolicyOverrideTransferScope"}]},"newLimit":{"type":"object","properties":{"amount":{"anyOf":[{"type":"string"},{"type":"number"}]},"assetId":{"enum":["USD"]}},"required":["amount","assetId"],"additionalProperties":false}},"required":["type","capability","limitType","scope","newLimit"],"additionalProperties":false,"title":"PolicyOverrideScopedAmountLimitOperation"},{"type":"object","properties":{"type":{"enum":["increase_limit"]},"capability":{"enum":["send","transfer"],"type":"string"},"limitType":{"enum":["hourly_count","daily_count"],"type":"string"},"scope":{"anyOf":[{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]},"counterparties":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["counterparty"]},"counterpartyId":{"type":"string","minLength":1}},"required":["type","counterpartyId"],"additionalProperties":false}]}},"required":["accounts","counterparties"],"additionalProperties":false,"title":"PolicyOverrideSendScope"},{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]}},"required":["accounts"],"additionalProperties":false,"title":"PolicyOverrideTransferScope"}]},"newLimit":{"type":"object","properties":{"count":{"type":"integer","minimum":1}},"required":["count"],"additionalProperties":false}},"required":["type","capability","limitType","scope","newLimit"],"additionalProperties":false,"title":"PolicyOverrideScopedCountLimitOperation"}]},"minItems":1,"maxItems":10},"durationSeconds":{"type":"integer","minimum":60,"maximum":604800},"reason":{"type":"string","minLength":1,"maxLength":280}},"required":["type","schemaVersion","operations","durationSeconds","reason"]},{"type":"object","properties":{"type":{"enum":["policy_proposal"]},"schemaVersion":{"enum":[1]},"rationale":{"type":"string","minLength":1,"maxLength":280},"proposedCounterparties":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":40},"email":{"type":"string","format":"email"},"rails":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"enum":["bank"]},"bankName":{"type":"string","minLength":1},"routingNumber":{"type":"string","pattern":"^\\d{9}$"},"accountNumber":{"type":"string","pattern":"^\\d{4,17}$"},"accountType":{"enum":["checking","savings"],"type":"string"},"address":{"type":"string"},"addressStreet":{"type":"string","minLength":3,"maxLength":35},"addressCity":{"type":"string","minLength":1},"addressState":{"type":"string"},"addressPostalCode":{"type":"string"},"addressCountry":{"type":"string"}},"required":["type","bankName","routingNumber","accountNumber","addressStreet","addressCity","addressState","addressPostalCode"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["wallet"]},"walletAddress":{"type":"string","minLength":1},"network":{"enum":["base","arc"],"type":"string"},"disabledNetworks":{"type":"array","items":{"enum":["base","arc"],"type":"string"}}},"required":["type","walletAddress","network"],"additionalProperties":false}]},"minItems":1,"maxItems":10}},"required":["ref","name"],"additionalProperties":false},"maxItems":25},"policy":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","maxLength":280},"counterpartyAccess":{"oneOf":[{"type":"object","properties":{"mode":{"enum":["open"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"enum":["restricted"]},"counterparties":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"enum":["existing"]},"counterpartyId":{"type":"string","minLength":1}},"required":["type","counterpartyId"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["proposed"]},"ref":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,63}$"}},"required":["type","ref"],"additionalProperties":false}]},"maxItems":200}},"required":["mode","counterparties"],"additionalProperties":false}]},"permissions":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"enum":["read"]},"accounts":{"oneOf":[{"type":"object","properties":{"mode":{"enum":["all"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"enum":["selected"]},"entries":{"type":"array","items":{"type":"object","properties":{"account":{"type":"object","properties":{"type":{"enum":["existing"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}},"required":["account"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["mode","entries"],"additionalProperties":false}]}},"required":["type","accounts"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["send"]},"accounts":{"oneOf":[{"type":"object","properties":{"mode":{"enum":["all"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"enum":["selected"]},"entries":{"type":"array","items":{"type":"object","properties":{"account":{"type":"object","properties":{"type":{"enum":["existing"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}},"required":["account"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["mode","entries"],"additionalProperties":false}]}},"required":["type","accounts"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["transfer"]},"accounts":{"oneOf":[{"type":"object","properties":{"mode":{"enum":["all"]}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"enum":["selected"]},"entries":{"type":"array","items":{"type":"object","properties":{"account":{"type":"object","properties":{"type":{"enum":["existing"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}},"required":["account"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["mode","entries"],"additionalProperties":false}]}},"required":["type","accounts"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["create_counterparty"]},"requiresApproval":{"type":"boolean"}},"required":["type","requiresApproval"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["request_counterparty_details"]},"requiresApproval":{"type":"boolean"}},"required":["type","requiresApproval"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["request_temporary_override"]}},"required":["type"],"additionalProperties":false}]},"minItems":1},"rules":{"type":"object","properties":{"send":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]},"counterparties":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["counterparty"]},"counterparty":{"oneOf":[{"type":"object","properties":{"type":{"enum":["existing"]},"counterpartyId":{"type":"string","minLength":1}},"required":["type","counterpartyId"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["proposed"]},"ref":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_-]{0,63}$"}},"required":["type","ref"],"additionalProperties":false}]}},"required":["type","counterparty"],"additionalProperties":false}]}},"required":["accounts","counterparties"],"additionalProperties":false},"limit":{"type":"object","properties":{"type":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"threshold":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"enum":["USD"]}},"required":["amount","assetId"],"additionalProperties":false}},"required":["type","threshold"],"additionalProperties":false},"action":{"oneOf":[{"type":"object","properties":{"type":{"enum":["block"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["require_approval"]},"requiredApprovals":{"enum":[1]}},"required":["type","requiredApprovals"],"additionalProperties":false}]}},"required":["scope","limit","action"],"additionalProperties":false},"maxItems":100},"transfer":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"object","properties":{"accounts":{"oneOf":[{"type":"object","properties":{"type":{"enum":["all"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["account"]},"accountId":{"type":"string","minLength":1}},"required":["type","accountId"],"additionalProperties":false}]}},"required":["accounts"],"additionalProperties":false},"limit":{"type":"object","properties":{"type":{"enum":["per_transaction_amount","daily_amount","weekly_amount","monthly_amount"],"type":"string"},"threshold":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"enum":["USD"]}},"required":["amount","assetId"],"additionalProperties":false}},"required":["type","threshold"],"additionalProperties":false},"action":{"oneOf":[{"type":"object","properties":{"type":{"enum":["block"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"enum":["require_approval"]},"requiredApprovals":{"enum":[1]}},"required":["type","requiredApprovals"],"additionalProperties":false}]}},"required":["scope","limit","action"],"additionalProperties":false},"maxItems":100}},"required":["send","transfer"],"additionalProperties":false},"evidenceRequirements":{"type":"object","properties":{"fields":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"additionalProperties":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":80},"instructions":{"type":"string","maxLength":500},"accepts":{"type":"array","items":{"enum":["text","image"],"type":"string"},"minItems":1}},"required":["label","accepts"],"additionalProperties":false}},"requiredByCapability":{"type":"object","properties":{"send":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"maxItems":20},"transfer":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"maxItems":20},"create_counterparty":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"maxItems":20},"request_counterparty_details":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"maxItems":20},"policy_override":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"maxItems":20}},"required":[],"additionalProperties":false}},"required":["fields","requiredByCapability"],"additionalProperties":false}},"required":["name","counterpartyAccess","permissions","rules"],"additionalProperties":false}},"required":["type","schemaVersion","rationale","policy"],"additionalProperties":false}]},"evidence":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"object","properties":{"attachmentId":{"type":"string","pattern":"^att_[0-9A-HJKMNP-TV-Z]{26}$","description":"An attachment this agent uploaded, once its status is ready"}},"required":["attachmentId"],"additionalProperties":false}]},"description":"Evidence for the action, keyed by the field keys the agent's policy requires for its capability: text, or `{ attachmentId }` for a file uploaded through POST /evidence-attachments. Leave it out, or send an empty object, when the policy requires none. x402 and mpp payments carry send evidence as text only, which a payment that resumes a pending approval or grant ignores. policy_proposal actions cannot carry evidence"}},"required":["action"]}}}},"responses":{"200":{"description":"Intent created and evaluated. A `send` or wallet-source `transfer` from a non-custodial (Turnkey) account returns an additional `nextAction` object (a `submit_stamp` envelope) with the unsigned body to stamp and submit to POST /intents/{intentId}/submit-stamp. A `policy_proposal` needs no policy and always waits for a person to approve it; it carries `proposal.reason`, as GET /intents/{id} does, and replaces the agent's earlier proposal if one is still pending.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Resolved source account, pinned when the intent was created. Omitted for actions without an account."},"type":{"enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"],"type":"string"},"status":{"enum":["pending","processing","completed","blocked","failed"],"type":"string"},"resolution":{"anyOf":[{"anyOf":[{"enum":["completed","blocked","denied","expired","failed","cancelled"],"type":"string"},{"type":"string","pattern":"\\S"}]},{"type":"null"}],"description":"Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings."},"reasons":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"replayed":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"counterparty":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"createdAt":{"type":"string"},"status":{"enum":["ready","awaiting_details"],"type":"string"},"rails":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"counterpartyId":{"type":"string"},"createdAt":{"type":"string"},"type":{"enum":["bank"]},"bankName":{"type":"string"},"routingNumber":{"type":"string"},"accountNumber":{"type":"string"},"accountType":{"enum":["checking","savings"],"type":"string"},"address":{"type":"string"},"addressStreet":{"type":"string"},"addressCity":{"type":"string"},"addressState":{"type":"string"},"addressPostalCode":{"type":"string"},"addressCountry":{"type":"string"},"providerExternalAccountId":{"type":"string"}},"required":["id","counterpartyId","createdAt","type","bankName","routingNumber","accountNumber"]},{"type":"object","properties":{"id":{"type":"string"},"counterpartyId":{"type":"string"},"createdAt":{"type":"string"},"type":{"enum":["wallet"]},"walletAddress":{"type":"string"},"network":{"enum":["base","arc"],"type":"string"},"asset":{"type":"string"}},"required":["id","counterpartyId","createdAt","type","walletAddress","network"]}]}}},"required":["id","name","createdAt","status","rails"]}},"required":["counterparty"]},{"type":"null"},{"type":"object","properties":{"transaction":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["operator-send","operator-transfer","operator-deposit","operator-refund","microdeposit"],"type":"string"},"action":{"type":"string"},"status":{"enum":["pending","processing","completed","failed","reversed"],"type":"string"},"movementStatus":{"enum":["initiated","provider_pending","processing","completed","failed","reversed","manual_review"],"type":"string"},"direction":{"enum":["incoming","outgoing"],"type":"string"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"USD amount. With tokenDetails, the settled recipient credit, or zero for a movement within the same account. Otherwise the recorded transaction amount."},"fee":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"With tokenDetails, the net account debit beyond amount, in USD at par, including fees, conversion cost and customer-paid gas. A negative value is a net conversion credit. Otherwise the recorded Catena fee."},"tokenDetails":{"type":"object","properties":{"debited":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string","description":"Token symbol in the same lower-case vocabulary as balance holdings.asset"},"network":{"type":"string","description":"Network on which the token left or arrived"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Net quantity of this token on this network, valued in USD at par"}},"required":["asset","network","amount"]},"description":"Tokens netted out of the viewed account, one entry per token and network"},"credited":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string","description":"Token symbol in the same lower-case vocabulary as balance holdings.asset"},"network":{"type":"string","description":"Network on which the token left or arrived"},"amount":{"type":"object","properties":{"amount":{"type":"string"},"assetId":{"type":"string"},"asset_id":{"type":"string","deprecated":true}},"required":["amount","assetId","asset_id"],"description":"Net quantity of this token on this network, valued in USD at par"}},"required":["asset","network","amount"]},"description":"Tokens netted into the viewed account, including conversion surplus, one entry per token and network"},"paid":{"type":"string","description":"Destination token symbol, only when a payment converted a different funding token"}},"required":["debited","credited"],"description":"Optional settled token detail for this account. Primary amounts are USD at par; balance holdings use the same asset vocabulary. Omitted when token provenance is unavailable or the organization has no held-asset entitlement."},"currency":{"type":"string"},"network":{"type":"string"},"counterpartyName":{"type":"string"},"method":{"enum":["ach","wire","on-chain"],"type":"string"},"memo":{"type":"string"},"description":{"type":"string"},"txHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["id","type","action","status","movementStatus","direction","amount","fee","currency","createdAt"]}},"required":["transaction"]},{"type":"object","properties":{"counterpartyId":{"type":"string"},"counterpartyName":{"type":"string"},"invite":{"type":"null"}},"required":["counterpartyId","counterpartyName","invite"]}]},"nextAction":{"type":"object","properties":{"type":{"enum":["submit_stamp"]},"signingRequestId":{"type":"string"},"signer":{"type":"object","properties":{"algorithm":{"enum":["p256"]},"publicKeyHex":{"type":"string","pattern":"^0[23][0-9a-f]{64}$"}},"required":["algorithm","publicKeyHex"]},"preparedBody":{"type":"object","properties":{"body":{"type":"string"},"bodyHash":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"prepareToken":{"type":"string"}},"required":["body","bodyHash","expiresAt","prepareToken"]},"movement":{"type":"object","properties":{"planId":{"type":"string"},"signerAddress":{"type":"string"},"digests":{"type":"array","items":{"type":"string"}},"instructions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"network":{"type":"string"},"signerAddress":{"type":"string"},"digest":{"type":"string"},"payload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"validBefore":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["kind","network","signerAddress","digest","payload","validBefore"]}}},"required":["planId","signerAddress","digests","instructions"]},"steps":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"preparedBody":{"type":"object","properties":{"body":{"type":"string"},"bodyHash":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"prepareToken":{"type":"string"}},"required":["body","bodyHash","expiresAt","prepareToken"]},"effects":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"enum":["out"]},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"to":{"type":"string"}},"required":["type","network","asset","amount","to"]},{"type":"object","properties":{"type":{"enum":["convert"]},"network":{"type":"string"},"inputAsset":{"type":"string"},"inputAmount":{"type":"string"},"outputNetwork":{"type":"string"},"outputAsset":{"type":"string"},"minOutputAmount":{"type":"string"}},"required":["type","network","inputAsset","inputAmount","outputNetwork","outputAsset","minOutputAmount"]},{"type":"object","properties":{"type":{"enum":["allowance"]},"network":{"type":"string"},"asset":{"type":"string"},"spender":{"type":"string"},"amount":{"type":"string"}},"required":["type","network","asset","spender","amount"]},{"type":"object","properties":{"type":{"enum":["bridge"]},"network":{"type":"string"},"toNetwork":{"type":"string"},"asset":{"enum":["usdc"]},"amount":{"type":"string"},"to":{"type":"string"},"maxFee":{"type":"string"}},"required":["type","network","toNetwork","asset","amount","to","maxFee"]},{"type":"object","properties":{"type":{"enum":["delegation"]},"network":{"type":"string"},"contract":{"type":"string"}},"required":["type","network","contract"]},{"type":"object","properties":{"type":{"enum":["native"]},"network":{"type":"string"},"maxAmountWei":{"type":"string"}},"required":["type","network","maxAmountWei"]}]}},"encoding":{"enum":["turnkey_sign_raw_payloads"]},"payloads":{"type":"array","items":{"type":"object","properties":{"instructionId":{"type":"string"},"legId":{"type":"string"},"network":{"type":"string"},"kind":{"enum":["evm_raw_transaction","eip3009_transfer_authorization","eip7702_delegation","eip712_execution"],"type":"string"},"digest":{"type":"string"},"payload":{"type":"object"}},"required":["instructionId","legId","network","kind","digest","payload"]}}},"required":["id","description","preparedBody","effects","encoding","payloads"]},{"type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"preparedBody":{"type":"object","properties":{"body":{"type":"string"},"bodyHash":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"prepareToken":{"type":"string"}},"required":["body","bodyHash","expiresAt","prepareToken"]},"effects":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"enum":["out"]},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"to":{"type":"string"}},"required":["type","network","asset","amount","to"]},{"type":"object","properties":{"type":{"enum":["convert"]},"network":{"type":"string"},"inputAsset":{"type":"string"},"inputAmount":{"type":"string"},"outputNetwork":{"type":"string"},"outputAsset":{"type":"string"},"minOutputAmount":{"type":"string"}},"required":["type","network","inputAsset","inputAmount","outputNetwork","outputAsset","minOutputAmount"]},{"type":"object","properties":{"type":{"enum":["allowance"]},"network":{"type":"string"},"asset":{"type":"string"},"spender":{"type":"string"},"amount":{"type":"string"}},"required":["type","network","asset","spender","amount"]},{"type":"object","properties":{"type":{"enum":["bridge"]},"network":{"type":"string"},"toNetwork":{"type":"string"},"asset":{"enum":["usdc"]},"amount":{"type":"string"},"to":{"type":"string"},"maxFee":{"type":"string"}},"required":["type","network","toNetwork","asset","amount","to","maxFee"]},{"type":"object","properties":{"type":{"enum":["delegation"]},"network":{"type":"string"},"contract":{"type":"string"}},"required":["type","network","contract"]},{"type":"object","properties":{"type":{"enum":["native"]},"network":{"type":"string"},"maxAmountWei":{"type":"string"}},"required":["type","network","maxAmountWei"]}]}},"encoding":{"enum":["turnkey_execute_swap"]},"swap":{"type":"object","properties":{"instructionId":{"type":"string"},"legId":{"type":"string"},"network":{"type":"string"},"onchainNonce":{"type":"string"},"quoteId":{"type":"string"},"inputToken":{"type":"string"},"inputAmount":{"type":"string"},"outputToken":{"type":"string"},"quotedOutputAmount":{"type":"string"},"minOutputAmount":{"type":"string"},"quoteExpiresAt":{"type":"string","format":"date-time"}},"required":["instructionId","legId","network","onchainNonce","quoteId","inputToken","inputAmount","outputToken","quotedOutputAmount","minOutputAmount","quoteExpiresAt"]}},"required":["id","description","preparedBody","effects","encoding","swap"]}]}},"totals":{"type":"object","properties":{"amount":{"type":"string"},"maxTotalDebit":{"type":"string"},"destination":{"type":"object","properties":{"recipient":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"}},"required":["recipient","network","asset"]},"signerAddress":{"type":"string"},"destinations":{"type":"array","items":{"type":"object","properties":{"recipient":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"}},"required":["recipient","network","asset"]},"description":"Every location the payment arrives at, one per network and asset, when that is not just `destination`. Transfers between the organization's own accounts deliver each admitted asset separately on its source's network. Mixed-asset deliveries include the exact amount at each location; only locations that receive funds are listed."},"sponsoredFees":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"amount":{"type":"string"}},"required":["network","amount"]},"description":"The crossing fee Catena restores to the signing wallet on each network a staged crossing lands on. Not part of `maxTotalDebit`, which counts only what the wallet pays."}},"required":["amount","maxTotalDebit","destination","signerAddress"]}},"required":["type","signingRequestId","signer","preparedBody"]},"proposal":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether this policy proposal can go ahead, without naming the resource or its state. While `status` is pending, null means the proposal passes every check made before a person reviews it; wait on awaiting_resources (something it needs, such as an active account, is not ready yet) and temporarily_unavailable (the check could not finish; read again later), and resubmit on referenced_resource_unavailable (an account or counterparty it names cannot be used) and proposal_invalid (it cannot be approved as written). While it is pending, it does not reflect whether a counterparty the proposal would create matches an existing one or shares an existing one's name, or what a wallet name (ENS) resolves to; only the person reviewing it sees those. When `resolution` is blocked, it is the reason the approval attempt recorded. In every other state it is null, and `status` and `resolution` give the outcome."}},"required":["reason"]},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"contentType":{"type":"string","description":"The media type verified from the file's bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name the agent gave the file, if any"}},"required":["contentType","sizeBytes","sha256Hex","filename"]}]},"description":"The evidence submitted with the intent, keyed by field key: text exactly as sent, or a file's details. Absent when the intent carries none"},"metadata":{"type":"object","properties":{"dataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataUrl"],"description":"Present while the intent waits for a person's approval: dataUrl is the console page where they decide it"}},"required":["id","type","status","resolution","reasons","expiresAt","replayed","data"]}}}},"400":{"description":"Input invalid, including an accountless send when multiple source accounts are allowed (`policy_send_account_required`), a policy proposal that could never be approved as written (`policy_proposal_invalid`, with each problem in `details.issues`), or a policy proposal naming an account or counterparty it cannot use (`policy_proposal_reference_unavailable`, which does not say which)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"Account not accessible under this policy, an accountless send has no allowed source (`policy_send_account_unavailable`), or policy proposals, or evidence requirements for a proposal that carries them, are not enabled for the organization (`feature_disabled`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Agent or referenced counterparty resource not found. Payment recipient failures may include `details.requiredRail`, which can be submitted in a create-counterparty intent","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"anyOf":[{"enum":["x402_counterparty_rail_not_found","mpp_counterparty_rail_not_found"],"type":"string"},{"type":"null"}]},"details":{"anyOf":[{"type":"object","properties":{"requiredRail":{"type":"object","properties":{"type":{"enum":["wallet"]},"walletAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"network":{"type":"string","description":"Server-resolved product network identifier accepted by counterparty creation"}},"required":["type","walletAddress","network"]}},"required":["requiredRail"]},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Intent conflicts, including idempotency-key reuse with changed request parameters, an inferred source that changed during submission (`policy_send_account_changed`), another payment from the same wallet still being approved (`movement_wallet_approval_open`; `details.heldUntil` is when the payment holding the wallet frees it, with the seconds until then in `Retry-After`, and is null when that cannot be told, as while that payment is being signed; wait until then, or a few seconds when it is null, then send the request again, on a new idempotency key when `details.intentCancelled` is true, because this request's intent was cancelled and its key answers with that cancelled intent, and on the same key when it is false, because the intent is still open (if it has been cancelled since, that resend returns it and nothing moved, so start again on a new key); `details.blockingIntentId` names the payment holding the wallet when it is one of your own intents, and cancelling it frees the wallet at once), a retried send that now crosses networks while its earlier request is still open (`cross_chain_send_movement_required`; have the earlier request denied or let it expire, or have Catena support close it if it was already approved, then start the payment again on a new idempotency key), a network Catena has made temporarily unavailable (`onchain_network_closed`, with no `Retry-After`; the request changed nothing and payments already in progress complete; do not retry on that network, and use one named in `details.alternatives` instead), an existing payment details request with safe invitation state, or evidence naming an attachment that is not ready yet (`evidence_attachments_not_ready`; `details.fields` names its fields; send the same request again, on the same idempotency key, once the attachment's status is ready). Also refused when the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","headers":{"Retry-After":{"description":"Seconds until the payment holding the wallet frees it. Sent with `movement_wallet_approval_open` when `details.heldUntil` is set","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"details":{"anyOf":[{"type":"object","properties":{"invite":{"anyOf":[{"type":"object","properties":{"state":{"enum":["outstanding","expired"],"type":"string"},"expiresAt":{"type":"string"},"methods":{"type":"object","properties":{"bank":{"type":"boolean"},"wallet":{"type":"boolean"}},"required":["bank","wallet"]}},"required":["state","expiresAt","methods"]},{"type":"null"}]}},"required":["invite"]},{"type":"null"},{"type":"object","properties":{"network":{"type":"string"},"closedBy":{"enum":["catena"]},"alternatives":{"type":"array","items":{"type":"string"}}},"required":["network","closedBy","alternatives"]},{"type":"object","properties":{"blockingIntentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"heldUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"intentCancelled":{"type":"boolean"}},"required":["blockingIntentId","heldUntil","intentCancelled"]},{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"The evidence fields whose attachments are not ready yet"}},"required":["fields"]}]}},"required":["error"]}}}},"422":{"description":"The request's `evidence` does not meet the agent's policy's evidence requirements for the action (`evidence_requirements_not_met`, with every problem in `details.issues`), or its attachments together hold more than one intent may (`evidence_attachments_too_large`, with the limit in `details.maxBytes`). The submitted values are never echoed. Nothing was created, so send the request again with corrected evidence, on the same idempotency key","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"},"code":{"enum":["evidence_requirements_not_met"]},"details":{"type":"object","properties":{"policyId":{"type":"string","description":"The policy whose requirements were checked"},"policyVersion":{"type":"number"},"capability":{"type":"string","description":"The policy capability governing the action, such as send for send, x402 and mpp actions"},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"The evidence field key"},"reason":{"type":"string","description":"missing: the policy requires the field and it was not sent. unexpected: it was sent but the policy does not require it for this capability. wrong_representation: it was sent in a form the field does not accept. attachment_unavailable: the attachment it names cannot be used, because it does not exist, has expired, was rejected or failed, or another intent already used it; upload the file again"},"accepts":{"type":"array","items":{"type":"string"},"description":"The forms that satisfy the field, for every issue but unexpected"}},"required":["field","reason"]},"description":"Every problem with the evidence, in the policy's order"}},"required":["policyId","policyVersion","capability","issues"]}},"required":["error","code","details"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"enum":["evidence_attachments_too_large"]},"details":{"type":"object","properties":{"maxBytes":{"type":"number","description":"The most bytes one intent's attachments may hold together, each counted once"}},"required":["maxBytes"]}},"required":["error","code","details"]}]}}}},"429":{"description":"Too many bank payments were requested for the organization (`rate_limited`). Each bank payment counts against a per-organization budget of 60 a minute by default, shared by its agents and members, with no daily cap; send the request again after the `Retry-After` seconds","headers":{"Retry-After":{"description":"Seconds until the spent budget window resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"503":{"description":"Non-custodial wallet sending is not enabled, or a service the request needs is temporarily unavailable (`movement_admission_paused`, or `temporarily_unavailable` with the service in `details`). The request changed nothing, and payments already in progress complete; send it again after the `Retry-After` seconds","headers":{"Retry-After":{"description":"Seconds to wait before sending the request again. Sent with `movement_admission_paused` and `temporarily_unavailable`","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/intents/{id}":{"get":{"tags":["intents"],"summary":"Get an intent by id","security":[{"agentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Intent state. A completed payment intent's `data` carries `paymentCredential` (the credential to present to the seller) and `transaction` (the same shape send/transfer serve); `data.x402` is a deprecated protocol-named copy of both. A payment carried by a movement plan carries `movement`: its `nextStep` reads `wait` while a person decides it, an admin signs it, or its signature is in flight, then `done` or `blocked`. A payment a person approved is signed by an admin, not the agent; an agent that restarted before signing a payment nobody had to approve sends its original request again on the same Idempotency-Key. `status` cannot carry this on its own, because a payment an admin is signing and one whose signature is in flight both read `processing`. A policy proposal carries `proposal`, whose `reason` says whether to wait or resubmit; once completed, its `data` names the policy approval created and the counterparty each proposed reference became.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Resolved source account, pinned when the intent was created. Omitted for actions without an account."},"type":{"enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"],"type":"string"},"status":{"enum":["pending","processing","completed","blocked","failed"],"type":"string"},"resolution":{"anyOf":[{"anyOf":[{"enum":["completed","blocked","denied","expired","failed","cancelled"],"type":"string"},{"type":"string","pattern":"\\S"}]},{"type":"null"}],"description":"Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings."},"reasons":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"movement":{"type":"object","properties":{"planId":{"type":"string"},"nextStep":{"enum":["wait","done","blocked"],"type":"string"}},"required":["planId","nextStep"]},"proposal":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether this policy proposal can go ahead, without naming the resource or its state. While `status` is pending, null means the proposal passes every check made before a person reviews it; wait on awaiting_resources (something it needs, such as an active account, is not ready yet) and temporarily_unavailable (the check could not finish; read again later), and resubmit on referenced_resource_unavailable (an account or counterparty it names cannot be used) and proposal_invalid (it cannot be approved as written). While it is pending, it does not reflect whether a counterparty the proposal would create matches an existing one or shares an existing one's name, or what a wallet name (ENS) resolves to; only the person reviewing it sees those. When `resolution` is blocked, it is the reason the approval attempt recorded. In every other state it is null, and `status` and `resolution` give the outcome."}},"required":["reason"]},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"contentType":{"type":"string","description":"The media type verified from the file's bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name the agent gave the file, if any"}},"required":["contentType","sizeBytes","sha256Hex","filename"]}]},"description":"The evidence submitted with the intent, keyed by field key: text exactly as sent, or a file's details. Absent when the intent carries none"},"data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"},{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"counterparties":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"outcome":{"enum":["created","reused"],"type":"string"}},"required":["ref","id","name","outcome"]}}},"required":["policy","counterparties"],"description":"A completed policy proposal: the policy its approval created, and the counterparty each proposed reference became. A counterparty deleted since, or one the current policy does not list, is left out."}]},"metadata":{"type":"object","properties":{"dataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataUrl"]}},"required":["id","type","status","resolution","reasons","expiresAt","data","metadata"]}}}},"404":{"description":"Intent missing or not owned by the authenticated agent (`intent_not_found`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/evidence-attachments":{"post":{"tags":["evidence"],"summary":"Ask for a form to upload a file the policy asks for as evidence","security":[{"agentBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Names the upload. Repeating the request with the same key and the same file returns the same attachment while it is usable: with a newly signed form while it awaits the file, without one after.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","description":"The file's media type: image/png, image/jpeg or image/webp"},"sizeBytes":{"type":"number","description":"The file's length in bytes"},"sha256Hex":{"type":"string","description":"The SHA-256 digest of the file, in lowercase hex"},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"A name to show people looking at the evidence; never trusted"}},"required":["contentType","sizeBytes","sha256Hex"]}}}},"responses":{"200":{"description":"The attachment this key already names, with a new form while it still awaits the file","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","description":"awaiting_upload: post the file with the upload form. processing: Catena is scanning and checking it. ready: an intent can use it. rejected: the file was refused, for outcomeReason. failed: ask for the upload again and send the file again"},"outcomeReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why a rejected or failed attachment ended, such as malware, hash_mismatch, animated or not_uploaded; null otherwise"},"contentType":{"type":"string","description":"The declared media type, and once ready the one verified from the bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string","description":"When the attachment is removed unless an intent has used it first"},"intentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The intent that used the attachment as evidence; null until one does"}},"required":["id","state","outcomeReason","contentType","sizeBytes","sha256Hex","filename","expiresAt","intentId"]},"upload":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"type":"string"}},"required":["url","fields","expiresAt"],"description":"POST the file to url as multipart/form-data: every field as given, then the file last, named file"},{"type":"null"}],"description":"The form to post the file with, while the attachment awaits it; null once it has landed"}},"required":["attachment","upload"]}}}},"201":{"description":"A new attachment, awaiting the file. Post it with `upload` before `upload.expiresAt`, then read the attachment until it is ready, rejected or failed","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","description":"awaiting_upload: post the file with the upload form. processing: Catena is scanning and checking it. ready: an intent can use it. rejected: the file was refused, for outcomeReason. failed: ask for the upload again and send the file again"},"outcomeReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why a rejected or failed attachment ended, such as malware, hash_mismatch, animated or not_uploaded; null otherwise"},"contentType":{"type":"string","description":"The declared media type, and once ready the one verified from the bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string","description":"When the attachment is removed unless an intent has used it first"},"intentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The intent that used the attachment as evidence; null until one does"}},"required":["id","state","outcomeReason","contentType","sizeBytes","sha256Hex","filename","expiresAt","intentId"]},"upload":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"type":"string"}},"required":["url","fields","expiresAt"],"description":"POST the file to url as multipart/form-data: every field as given, then the file last, named file"},{"type":"null"}],"description":"The form to post the file with, while the attachment awaits it; null once it has landed"}},"required":["attachment","upload"]}}}},"400":{"description":"The request is malformed, has no Idempotency-Key (`idempotency_key_required`), or declares a media type or digest Catena does not accept","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"403":{"description":"The agent's policy asks for no file for anything it is granted (`evidence_attachments_not_accepted`), or the agent has no active policy (no `code`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"The key names an attachment that declared another file (`evidence_upload_key_reused`), its upload can no longer complete (`upload_closed`), or the agent is staging as many attachments or bytes as it may (`evidence_staging_quota_exceeded`, with both limits in `details`). Also refused when the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"413":{"description":"The declared file is larger than Catena accepts","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"503":{"description":"Evidence uploads are unavailable right now (`evidence_uploads_unavailable`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/evidence-attachments/{attachmentId}":{"get":{"tags":["evidence"],"summary":"Get an evidence attachment's status","security":[{"agentBearer":[]}],"parameters":[{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The attachment. It is removed a day after its upload was requested unless an intent has used it","content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","description":"awaiting_upload: post the file with the upload form. processing: Catena is scanning and checking it. ready: an intent can use it. rejected: the file was refused, for outcomeReason. failed: ask for the upload again and send the file again"},"outcomeReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why a rejected or failed attachment ended, such as malware, hash_mismatch, animated or not_uploaded; null otherwise"},"contentType":{"type":"string","description":"The declared media type, and once ready the one verified from the bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"type":"string","description":"When the attachment is removed unless an intent has used it first"},"intentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The intent that used the attachment as evidence; null until one does"}},"required":["id","state","outcomeReason","contentType","sizeBytes","sha256Hex","filename","expiresAt","intentId"]}},"required":["attachment"]}}}},"404":{"description":"Attachment missing, expired or not the authenticated agent's (`evidence_attachment_not_found`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/intents/{intentId}/cancel":{"post":{"tags":["intents"],"summary":"Cancel an intent before execution starts","security":[{"agentBearer":[]}],"parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full intent state after cancellation. Repeating the request for an already-cancelled intent returns the same successful projection. Cancellation is only available before execution starts and cannot stop or reverse work already executing.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Resolved source account, pinned when the intent was created. Omitted for actions without an account."},"type":{"enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"],"type":"string"},"status":{"enum":["pending","processing","completed","blocked","failed"],"type":"string"},"resolution":{"anyOf":[{"anyOf":[{"enum":["completed","blocked","denied","expired","failed","cancelled"],"type":"string"},{"type":"string","pattern":"\\S"}]},{"type":"null"}],"description":"Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings."},"reasons":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"movement":{"type":"object","properties":{"planId":{"type":"string"},"nextStep":{"enum":["wait","done","blocked"],"type":"string"}},"required":["planId","nextStep"]},"proposal":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether this policy proposal can go ahead, without naming the resource or its state. While `status` is pending, null means the proposal passes every check made before a person reviews it; wait on awaiting_resources (something it needs, such as an active account, is not ready yet) and temporarily_unavailable (the check could not finish; read again later), and resubmit on referenced_resource_unavailable (an account or counterparty it names cannot be used) and proposal_invalid (it cannot be approved as written). While it is pending, it does not reflect whether a counterparty the proposal would create matches an existing one or shares an existing one's name, or what a wallet name (ENS) resolves to; only the person reviewing it sees those. When `resolution` is blocked, it is the reason the approval attempt recorded. In every other state it is null, and `status` and `resolution` give the outcome."}},"required":["reason"]},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"contentType":{"type":"string","description":"The media type verified from the file's bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name the agent gave the file, if any"}},"required":["contentType","sizeBytes","sha256Hex","filename"]}]},"description":"The evidence submitted with the intent, keyed by field key: text exactly as sent, or a file's details. Absent when the intent carries none"},"data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"},{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"counterparties":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"outcome":{"enum":["created","reused"],"type":"string"}},"required":["ref","id","name","outcome"]}}},"required":["policy","counterparties"],"description":"A completed policy proposal: the policy its approval created, and the counterparty each proposed reference became. A counterparty deleted since, or one the current policy does not list, is left out."}]},"metadata":{"type":"object","properties":{"dataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataUrl"]}},"required":["id","type","status","resolution","reasons","expiresAt","data","metadata"]}}}},"404":{"description":"Intent missing or not owned by the authenticated agent (`intent_not_found`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Intent is not eligible for cancellation (`intent_not_cancellable`). Also refused when the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/intents/{intentId}/submit-stamp":{"post":{"tags":["intents"],"summary":"Submit a stamped Turnkey body for a non-custodial send intent (second phase of a wallet send)","security":[{"agentBearer":[]}],"parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"preparedBody":{"type":"object","properties":{"body":{"type":"string"},"bodyHash":{"type":"string","minLength":1},"expiresAt":{"type":"string","format":"date-time"},"prepareToken":{"type":"string","minLength":1}},"required":["body","bodyHash","expiresAt","prepareToken"]},"stamp":{"type":"object","properties":{"publicKeyHex":{"type":"string","minLength":1},"stampHeaderName":{"type":"string","minLength":1},"stampHeaderValue":{"type":"string"}},"required":["publicKeyHex","stampHeaderName","stampHeaderValue"]}},"required":["preparedBody","stamp"],"additionalProperties":false},{"type":"object","properties":{"stamps":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string","minLength":1,"maxLength":128},"preparedBody":{"type":"object","properties":{"body":{"type":"string"},"bodyHash":{"type":"string","minLength":1},"expiresAt":{"type":"string","format":"date-time"},"prepareToken":{"type":"string","minLength":1}},"required":["body","bodyHash","expiresAt","prepareToken"]},"stamp":{"type":"object","properties":{"publicKeyHex":{"type":"string","minLength":1},"stampHeaderName":{"type":"string","minLength":1},"stampHeaderValue":{"type":"string"}},"required":["publicKeyHex","stampHeaderName","stampHeaderValue"]}},"required":["stepId","preparedBody","stamp"]},"minItems":1,"maxItems":9}},"required":["stamps"],"additionalProperties":false}],"description":"Send either the prepared body with its stamp, or a stamp for every step of the next action, never both.","type":"object"}}}},"responses":{"200":{"description":"Stamp submitted. Wallet sends answer with the external status; payment intents answer with status `completed` plus `paymentCredential` — the credential to present to the seller (for x402, the PAYMENT-SIGNATURE header value to retry the 402 with). The `x402` object is a deprecated protocol-named copy of the same value.","content":{"application/json":{"schema":{"type":"object","properties":{"intentId":{"type":"string"},"signingRequestId":{"type":"string"},"status":{"enum":["user_presence_required","consensus_needed","broadcast","confirmed","rejected","manual_review","failed","completed","authorized","executing","cancelled","expired"],"type":"string"},"planId":{"type":"string"},"x402":{"type":"object","properties":{"paymentSignature":{"type":"string"}},"required":["paymentSignature"],"deprecated":true},"paymentCredential":{"type":"object","properties":{"protocol":{"enum":["x402","mpp"],"type":"string","description":"Payment protocol the credential belongs to"},"value":{"type":"string","description":"Opaque credential to present to the seller; for x402, the PAYMENT-SIGNATURE header value"}},"required":["protocol","value"]},"intent":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string","description":"Resolved source account, pinned when the intent was created. Omitted for actions without an account."},"type":{"enum":["send","transfer","create_counterparty","request_counterparty_details","x402","mpp","policy_override","policy_proposal"],"type":"string"},"status":{"enum":["pending","processing","completed","blocked","failed"],"type":"string"},"resolution":{"anyOf":[{"anyOf":[{"enum":["completed","blocked","denied","expired","failed","cancelled"],"type":"string"},{"type":"string","pattern":"\\S"}]},{"type":"null"}],"description":"Exact terminal outcome, or null while the intent is nonterminal. Known values are completed, blocked, denied, expired, failed, and cancelled; clients must preserve future nonblank strings."},"reasons":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"movement":{"type":"object","properties":{"planId":{"type":"string"},"nextStep":{"enum":["wait","done","blocked"],"type":"string"}},"required":["planId","nextStep"]},"proposal":{"type":"object","properties":{"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether this policy proposal can go ahead, without naming the resource or its state. While `status` is pending, null means the proposal passes every check made before a person reviews it; wait on awaiting_resources (something it needs, such as an active account, is not ready yet) and temporarily_unavailable (the check could not finish; read again later), and resubmit on referenced_resource_unavailable (an account or counterparty it names cannot be used) and proposal_invalid (it cannot be approved as written). While it is pending, it does not reflect whether a counterparty the proposal would create matches an existing one or shares an existing one's name, or what a wallet name (ENS) resolves to; only the person reviewing it sees those. When `resolution` is blocked, it is the reason the approval attempt recorded. In every other state it is null, and `status` and `resolution` give the outcome."}},"required":["reason"]},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"contentType":{"type":"string","description":"The media type verified from the file's bytes"},"sizeBytes":{"type":"number"},"sha256Hex":{"type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name the agent gave the file, if any"}},"required":["contentType","sizeBytes","sha256Hex","filename"]}]},"description":"The evidence submitted with the intent, keyed by field key: text exactly as sent, or a file's details. Absent when the intent carries none"},"data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"},{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"counterparties":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"outcome":{"enum":["created","reused"],"type":"string"}},"required":["ref","id","name","outcome"]}}},"required":["policy","counterparties"],"description":"A completed policy proposal: the policy its approval created, and the counterparty each proposed reference became. A counterparty deleted since, or one the current policy does not list, is left out."}]},"metadata":{"type":"object","properties":{"dataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["dataUrl"]}},"required":["id","type","status","resolution","reasons","expiresAt","data","metadata"]}},"required":["intentId","signingRequestId","status"]}}}},"403":{"description":"Wallet-send intent does not belong to the calling agent","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Wallet-send intent or prepared row not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Wallet-send is no longer prepared, prepared body does not match, or Catena has made its network temporarily unavailable (`onchain_network_closed`, with no `Retry-After`). On a closed network nothing was submitted and no money moved, and a wallet send's intent failed with its hold released. Read the intent before creating a new one on a network named in `details.alternatives`. Also refused when the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"503":{"description":"Non-custodial wallet sending is not enabled, or sending is temporarily unavailable (`temporarily_unavailable`, with the service in `details`). Nothing was submitted and no money moved. The intent may have failed with its hold released; read it, and create a new intent once sending is available again. A submit an earlier attempt already claimed answers 409 instead","headers":{"Retry-After":{"description":"Seconds to wait before sending the request again. Sent with `temporarily_unavailable`","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/intents/{intentId}/settlement-report":{"post":{"tags":["intents"],"summary":"Report the facilitator's settlement transaction for a completed x402 payment","security":[{"agentBearer":[]}],"parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"receipt":{"oneOf":[{"type":"object","properties":{"format":{"enum":["eip712"]},"payload":{"type":"object","properties":{"version":{"enum":[1]},"network":{"type":"string","maxLength":64},"resourceUrl":{"type":"string","maxLength":2048},"payer":{"type":"string","maxLength":128},"issuedAt":{"type":"integer","minimum":0},"transaction":{"type":"string","maxLength":128}},"required":["version","network","resourceUrl","payer","issuedAt"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["format","payload","signature"]},{"type":"object","properties":{"format":{"enum":["jws"]},"signature":{"type":"string","maxLength":8192,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$"}},"required":["format","signature"]}]}},"required":["txHash"]}}}},"responses":{"200":{"description":"Settlement hint recorded. Stored as an untrusted hint only — on-chain verification remains the source of truth, and a payment with no settlement record yet still answers success.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"enum":[true]}},"required":["success"]}}}},"403":{"description":"Payment intent does not belong to the calling agent","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"404":{"description":"Payment intent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}},"409":{"description":"Intent is not an x402 payment","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable machine-readable identifier for the error condition"},"fields":{"description":"Validation explanations keyed by dotted request field path, such as action.memo. The request key represents a request-wide issue. Null when no field explanations are available.","anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]}},"required":["error"]}}}}}}},"/feedback":{"post":{"tags":["agent"],"summary":"Submit free-form agent feedback","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000}},"required":["body"]}}}},"responses":{"200":{"description":"Feedback recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"enum":[true]}},"required":["success"]}}}}}}}},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","description":"Agent session token (cat_sess_...)"},"operatorBearer":{"type":"http","scheme":"bearer","description":"Operator session token with operator role"}}}}