{ "openapi": "3.1.0", "info": { "title": "AgentWallet API", "version": "0.1.0", "description": "REST API for AgentWallet — the financial identity layer for autonomous AI agents. Wallets, virtual cards, USDC on Base, payout execution across 17 rails, AP2 mandates, ACP tokens, and per-agent spending policies. Machine clients authenticate with a pak_… API key (Authorization: Bearer …) or OAuth 2.1 + PKCE.", "contact": { "name": "AgentWallet", "url": "https://agentwallet.ai/developers" } }, "servers": [ { "url": "https://agentwallet.ai/api", "description": "Production" } ], "tags": [ { "name": "health", "description": "Health operations" }, { "name": "catalog", "description": "Live Payouts.com catalog" }, { "name": "onchain", "description": "On-chain registration (Base Sepolia)" }, { "name": "activity", "description": "Account activity feed" }, { "name": "inbox", "description": "Per-agent AgentMail inboxes" }, { "name": "payouts", "description": "Payout execution across all 17 Payouts.com rails" } ], "paths": { "/principals/{id}/register-on-chain": { "post": { "operationId": "registerPrincipalOnChain", "tags": [ "onchain" ], "summary": "Register a principal on Base Sepolia", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Registered (or already registered, returned via 409 below)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainRegistration" } } } }, "409": { "description": "Already registered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Chain RPC error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/register-on-chain": { "post": { "operationId": "registerAgentOnChain", "tags": [ "onchain" ], "summary": "Register an agent on Base Sepolia (auto-registers parent principal first if needed)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainRegistration" } } } }, "409": { "description": "Already registered", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Chain RPC error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/ensure-on-chain": { "post": { "operationId": "ensureAgentOnChain", "tags": [ "onchain" ], "summary": "Idempotent ensure — re-mints only if the cached on-chain id is stale, otherwise returns the agent unchanged", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent (with on-chain fields populated)", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "additionalProperties": true }, "rescued": { "type": "boolean", "description": "True when the cached on-chain id was stale and a fresh row was minted." } }, "required": [ "agent", "rescued" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Chain RPC error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/reissue-on-chain": { "post": { "operationId": "reissueAgentOnChain", "tags": [ "onchain" ], "summary": "Force re-mint of the agent's on-chain registry row (records previous on-chain id in the activity event)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent with the new on-chain identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "additionalProperties": true } }, "required": [ "agent" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Chain RPC error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/on-chain": { "delete": { "operationId": "deregisterAgentOnChain", "tags": [ "onchain" ], "summary": "Detach the agent's local on-chain pointers (the on-chain registry row itself is immutable and remains on-chain)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Agent with on-chain fields cleared locally", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "additionalProperties": true } }, "required": [ "agent" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Agent is not registered on-chain", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/activity": { "get": { "operationId": "listActivity", "tags": [ "activity" ], "summary": "Recent activity events for the caller's account", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeed" } } } } } } }, "/agents/{id}/inbox": { "post": { "operationId": "provisionAgentInbox", "tags": [ "inbox" ], "summary": "Create (or return existing) AgentMail inbox for the agent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Already provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProvisionResponse" } } } }, "201": { "description": "Newly created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProvisionResponse" } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "AgentMail not configured or rejected the request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAgentInbox", "tags": [ "inbox" ], "summary": "Detach and best-effort delete the agent's inbox", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detached", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/inbox/threads": { "get": { "operationId": "listAgentInboxThreads", "tags": [ "inbox" ], "summary": "List mail threads for the agent's inbox", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Threads (possibly empty if no inbox yet)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadList" } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/inbox/threads/{threadId}": { "get": { "operationId": "getAgentInboxThread", "tags": [ "inbox" ], "summary": "Get a single thread with its full message list", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "threadId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxThreadDetailResponse" } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent or thread not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/inbox/messages": { "post": { "operationId": "sendAgentInboxMessage", "tags": [ "inbox" ], "summary": "Send an outbound message from the agent's inbox", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInboxMessageInput" } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInboxMessageResponse" } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation or AgentMail rejection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/phone": { "get": { "operationId": "getAgentPhone", "tags": [ "agentPhone" ], "summary": "Current AgentSIM phone session for an agent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/AgentPhone" }, "configured": { "type": "boolean" } }, "required": [ "phone", "configured" ] } } } } } }, "post": { "operationId": "provisionAgentPhone", "tags": [ "agentPhone" ], "summary": "Provision a new AgentSIM number for the agent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "US" } } } } } }, "responses": { "201": { "description": "Provisioned", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/AgentPhone" } }, "required": [ "phone" ] } } } } } }, "delete": { "operationId": "releaseAgentPhone", "tags": [ "agentPhone" ], "summary": "Release the agent's active AgentSIM number", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Released (idempotent — succeeds even if already released)", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/AgentPhone" } }, "required": [ "phone" ] } } } } } } }, "/agents/{id}/phone/wait": { "post": { "operationId": "waitForAgentOtp", "tags": [ "agentPhone" ], "summary": "Long-poll AgentSIM for the next OTP (≤60s)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeoutSec": { "type": "integer", "minimum": 1, "maximum": 60, "default": 60 } } } } } }, "responses": { "200": { "description": "OTP if one arrived; null if the long-poll window elapsed", "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "oneOf": [ { "$ref": "#/components/schemas/AgentOtp" }, { "type": "null" } ] } }, "required": [ "otp" ] } } } } } } }, "/agents/{id}/phone/otps": { "get": { "operationId": "listAgentOtps", "tags": [ "agentPhone" ], "summary": "Paginated OTP history for one agent (newest first)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOtpFeed" } } } } } } }, "/accounts/mine/otps": { "get": { "operationId": "listAccountOtps", "tags": [ "agentPhone" ], "summary": "Account-wide OTP history (every agent), newest first", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOtpFeed" } } } } } } }, "/agents/{id}/cards/{resourceId}/reload": { "post": { "operationId": "reloadAgentCard", "tags": [ "cards" ], "summary": "Reload an already-issued virtual card via Payouts.com /v1/cards/{cardProxy}/reload", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "default": "USD" } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Reloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardReloadResponse" } } } }, "404": { "description": "Agent or card not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Card has no resolvable upstream cardProxy (legacy or synthetic record)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation or upstream rejection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/cards/{resourceId}": { "get": { "operationId": "getAgentCard", "tags": [ "cards" ], "summary": "Refresh card balance/status from Payouts.com /v1/cards/{cardProxy}", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSummaryResponse" } } } }, "404": { "description": "Agent or card not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Card has no resolvable upstream cardProxy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/cards/{resourceId}/loads": { "get": { "operationId": "listAgentCardLoads", "tags": [ "cards" ], "summary": "List reload history for a virtual card", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Reload history", "content": { "application/json": { "schema": { "type": "object", "properties": { "loads": { "type": "array", "items": { "$ref": "#/components/schemas/CardLoad" } } }, "required": [ "loads" ] } } } }, "404": { "description": "Agent or card not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Card has no resolvable upstream cardProxy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/agents/{id}": { "get": { "operationId": "getAcpAgentDiscovery", "tags": [ "acp" ], "summary": "Public ACP (Stripe Agentic Commerce Protocol) buyer-side discovery doc for an agent.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Discovery doc", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "role", "agent_id", "supports", "endpoints" ], "properties": { "version": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string", "nullable": true }, "agent_id": { "type": "string", "format": "uuid" }, "supports": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "object", "properties": { "issue_spt": { "type": "string" }, "pay_at_merchant": { "type": "string" } } }, "stripe_profile": { "type": "string", "nullable": true } } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/agents/{id}/readiness": { "get": { "operationId": "getAcpAgentReadiness", "tags": [ "acp" ], "summary": "Operator-facing readiness probe — discovery + Stripe SPT preflight (ensureCustomer + ensurePaymentMethod).", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Readiness result (always 200; check `ready` field).", "content": { "application/json": { "schema": { "type": "object", "required": [ "ready", "step", "code", "supports" ], "properties": { "ready": { "type": "boolean" }, "step": { "type": "string", "enum": [ "agent_card_unavailable", "ensure_customer", "ensure_payment_method", "ok" ] }, "code": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "supports": { "type": "array", "items": { "type": "string" } }, "stripeProfile": { "type": "string", "nullable": true }, "stripeCustomerId": { "type": "string", "nullable": true }, "stripePaymentMethodId": { "type": "string", "nullable": true }, "cardTokenRowId": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/agents/{id}/spts": { "post": { "operationId": "issueAcpAgentSpt", "tags": [ "acp" ], "summary": "PAK-authed — issue (or replay) an ACP Stripe SPT bound to (agent, card, cart, merchant).", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cartMandateUid", "amountUsd", "merchantRef" ], "properties": { "cartMandateUid": { "type": "string", "minLength": 1, "maxLength": 200 }, "amountUsd": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "currency": { "type": "string", "default": "USD", "minLength": 3, "maxLength": 3 }, "merchantRef": { "type": "string", "minLength": 1, "maxLength": 200 }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 3600 }, "cardTokenId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "SPT replayed (idempotency hit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpSptIssueResult" } } } }, "201": { "description": "SPT issued (first time)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpSptIssueResult" } } } }, "401": { "description": "Missing/invalid PAK", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation or upstream rejection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listAcpAgentSpts", "tags": [ "acp" ], "summary": "List recent ACP SPT issuances for an agent (session-auth, account-scoped).", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of recent SPTs", "content": { "application/json": { "schema": { "type": "object", "required": [ "spts" ], "properties": { "spts": { "type": "array", "items": { "type": "object", "required": [ "id", "sptId", "status", "amountMaxCents", "currency", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sptId": { "type": "string" }, "status": { "type": "string" }, "sellerRef": { "type": "string", "nullable": true }, "sellerStripeProfile": { "type": "string", "nullable": true }, "merchantOrderId": { "type": "string", "nullable": true }, "amountMaxCents": { "type": "integer" }, "currency": { "type": "string" }, "cartMandateUid": { "type": "string", "nullable": true }, "stripeSharedPaymentTokenId": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/agents/{id}/spts/{sptRowId}/revoke": { "post": { "operationId": "revokeAcpAgentSpt", "tags": [ "acp" ], "summary": "Revoke an ACP SPT row (session-auth, account-scoped).", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "sptRowId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/agents/{id}/mint-card-token": { "post": { "operationId": "mintAcpAgentCardToken", "tags": [ "acp" ], "summary": "Session-auth — mint a Stripe card token for the agent's active virtual card (self-serve UI shortcut to make ACP ready).", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replayed (idempotency hit on prior mint)", "content": { "application/json": { "schema": { "type": "object", "required": [ "stripeTokenId", "replayed" ], "properties": { "stripeTokenId": { "type": "string" }, "replayed": { "type": "boolean" } } } } } }, "201": { "description": "Newly minted", "content": { "application/json": { "schema": { "type": "object", "required": [ "stripeTokenId", "replayed" ], "properties": { "stripeTokenId": { "type": "string" }, "replayed": { "type": "boolean" } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Agent not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "No active virtual card on agent, or VGS misconfigured.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/acp/merchant/probe": { "post": { "operationId": "probeAcpMerchant", "tags": [ "acp" ], "summary": "Resolve (and optionally re-probe) a merchant's ACP capability via static allowlist + env + well-known discovery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ref" ], "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "refresh": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Discovery resolution", "content": { "application/json": { "schema": { "type": "object", "required": [ "discovery" ], "properties": { "discovery": { "type": "object", "required": [ "ref", "capable", "source", "expiresAt" ], "properties": { "ref": { "type": "string" }, "capable": { "type": "string", "enum": [ "yes", "no", "optimistic", "unknown" ] }, "source": { "type": "string" }, "acpBaseUrl": { "type": "string", "nullable": true }, "stripeAccount": { "type": "string", "nullable": true }, "stripeProfile": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "endpoints": { "type": "object", "nullable": true, "properties": { "base_url": { "type": "string" }, "create_checkout": { "type": "string" }, "complete_checkout": { "type": "string" } } }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } } } } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failure", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/payments/spt": { "post": { "operationId": "issueAgentSpt", "tags": [ "payments" ], "summary": "Issue a Stripe Shared Payment Token bound to (cardToken, amountCap, allowedMerchants, ttl). Idempotent by cartMandateUid.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cardTokenId", "amountUsd" ], "properties": { "cardTokenId": { "type": "string", "format": "uuid" }, "amountUsd": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "currency": { "type": "string", "default": "USD", "minLength": 3, "maxLength": 3 }, "allowedMerchants": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "cartMandateUid": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "SPT issued or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "replayed", "spt" ], "properties": { "replayed": { "type": "boolean" }, "spt": { "type": "object", "required": [ "id", "sptId", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sptId": { "type": "string" }, "stripeSharedPaymentTokenId": { "type": "string", "nullable": true }, "cardTokenId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string" }, "cartMandateUid": { "type": "string", "nullable": true } } } } } } } }, "201": { "description": "SPT issued (first time)", "content": { "application/json": { "schema": { "type": "object", "required": [ "replayed", "spt" ], "properties": { "replayed": { "type": "boolean" }, "spt": { "type": "object", "required": [ "id", "sptId", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sptId": { "type": "string" }, "stripeSharedPaymentTokenId": { "type": "string", "nullable": true }, "cardTokenId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string" }, "cartMandateUid": { "type": "string", "nullable": true } } } } } } } }, "401": { "description": "Missing/invalid PAK", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation or upstream rejection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/payments/spt/{sptId}": { "delete": { "operationId": "revokeAgentSpt", "tags": [ "payments" ], "summary": "Revoke a previously-issued Shared Payment Token.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "sptId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "Missing/invalid PAK", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "SPT not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/payments/card-token": { "post": { "operationId": "issueAgentCardToken", "tags": [ "payments" ], "summary": "Mint a single-use Stripe card token (`tok_...`) for the agent's persisted card.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Either omit the body entirely (server resolves the agent's\nactive virtual card and mints a fresh token) OR supply\n`cardTokenId` to re-mint into an existing issuance row.\n", "properties": { "cardTokenId": { "type": "string", "format": "uuid" }, "cartMandateUid": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Card token issued or replayed", "content": { "application/json": { "schema": { "type": "object", "required": [ "cardTokenId", "replayed" ], "properties": { "cardTokenId": { "type": "string" }, "replayed": { "type": "boolean" }, "fellBackFromSpt": { "type": "boolean" } } } } } }, "201": { "description": "Card token issued (first time)", "content": { "application/json": { "schema": { "type": "object", "required": [ "cardTokenId", "replayed" ], "properties": { "cardTokenId": { "type": "string" }, "replayed": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid PAK", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation or upstream rejection", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agents/{id}/payments/forward": { "post": { "operationId": "stripeForwardForAgent", "tags": [ "payments" ], "summary": "Stripe Forward to a non-Stripe processor. Requires VGS_PROXY_ENABLED.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cardTokenId", "destinationUrl" ], "properties": { "cardTokenId": { "type": "string", "format": "uuid" }, "destinationUrl": { "type": "string", "format": "uri" }, "destinationHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "destinationBody": { "type": "string", "maxLength": 64000 } } } } } }, "responses": { "200": { "description": "Forward succeeded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing/invalid PAK", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Forward not supported on this account (VGS proxy disabled)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/healthz": { "get": { "operationId": "healthCheck", "tags": [ "health" ], "summary": "Health check", "description": "Returns server health status", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } } } } }, "/catalog/payouts": { "get": { "operationId": "getPayoutsCatalog", "tags": [ "catalog" ], "summary": "Live Payouts.com catalog (countries, fiat collection, crypto collection, payout methods)", "description": "Pulls supported countries, fiat collection rails, crypto collection\nrails, and payout methods directly from the Payouts.com MCP server\non every request — never cached server-side. Also returns the\napproved subset for the signed-in account.\n", "responses": { "200": { "description": "Live catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutsCatalog" } } } }, "401": { "description": "Not authenticated" } } } }, "/agents/{id}/payouts": { "post": { "operationId": "sendAgentPayout", "tags": [ "payouts" ], "summary": "Execute a payout from this agent on any of the 17 rails", "description": "Enforces the 4-layer cascade (account approved ⊇ principal granted\n⊇ agent granted) and the runtime spend gate (per-tx, daily,\nmonthly). Persists a `payout_intents` row BEFORE the upstream call\nso failures never strand money. Idempotency is per-account on\n`idempotencyKey` — a replay returns the existing row verbatim.\nFor amounts ≥ $10,000 the first call returns\n`{step:\"confirm\", confirmationToken}` — the SPA must POST again\nwith the same idempotencyKey + the returned token to actually\nexecute. Lifecycle status flips (`completed`/`failed`/`returned`)\narrive asynchronously via `/api/webhooks/payouts`.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPayoutInput" } } } }, "responses": { "200": { "description": "Either an idempotency replay, a high-value confirmation\nchallenge, or a preflight failure. Discriminated by `step`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPayoutResponse" } } } }, "201": { "description": "Payout submitted upstream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPayoutOk" } } } }, "403": { "description": "Capability not approved or not granted at some layer" }, "422": { "description": "Spend gate denied (per-tx/daily/monthly cap)" } } }, "get": { "operationId": "listAgentPayouts", "tags": [ "payouts" ], "summary": "Paged history of payout intents for an agent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Payout history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutIntentFeed" } } } } } } }, "/payouts/{requestId}": { "get": { "operationId": "getPayoutByRequestId", "tags": [ "payouts" ], "summary": "Look up a single payout intent by cross-rail correlation key", "parameters": [ { "in": "path", "name": "requestId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Single payout intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "$ref": "#/components/schemas/PayoutIntent" } }, "required": [ "intent" ] } } } }, "404": { "description": "Not found" } } } }, "/capabilities/schema": { "post": { "operationId": "getCapabilitySchema", "tags": [ "payouts" ], "summary": "Per-rail+country form schema (forwards to Payouts.com /v1/capabilities/schema)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "type": "string" }, "country": { "type": "string" }, "currency": { "type": "string" }, "entityType": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ], "description": "Beneficiary entity kind — switches required-fields surface for several rails." }, "paymentData": { "type": "object", "additionalProperties": true, "description": "Partial draft of the rail-specific payload, used by the upstream to derive conditional sub-schemas." } }, "required": [ "capability" ] } } } }, "responses": { "200": { "description": "Capability schema", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/capabilities/quote": { "post": { "operationId": "getCapabilityQuote", "tags": [ "payouts" ], "summary": "Fee + FX quote (forwards to Payouts.com /v1/capabilities/quote)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "country": { "type": "string" }, "entityType": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "paymentData": { "type": "object", "additionalProperties": true } }, "required": [ "capability", "amount", "currency" ] } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/payouts/preflight": { "post": { "operationId": "preflightPayout", "tags": [ "payouts" ], "summary": "Dry-run a payout — fees, routing, and field-level fix-hints", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutPreflightInput" } } } }, "responses": { "200": { "description": "Preflight result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "schemas": { "AcpSptIssueResult": { "type": "object", "required": [ "replayed", "rail", "spt_id", "expires_at", "spt", "merchant" ], "properties": { "replayed": { "type": "boolean" }, "rail": { "type": "string", "enum": [ "spt" ] }, "spt_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "merchant": { "type": "object", "required": [ "ref", "capable", "stripe_profile" ], "properties": { "ref": { "type": "string" }, "capable": { "type": "string" }, "stripe_profile": { "type": "string" } } }, "spt": { "type": "object", "required": [ "id", "sptId", "status", "expiresAt", "cartMandateUid", "amountMaxCents", "currency", "cardTokenId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sptId": { "type": "string" }, "status": { "type": "string" }, "cardTokenId": { "type": "string", "format": "uuid" }, "stripeSharedPaymentTokenId": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "cartMandateUid": { "type": "string", "nullable": true }, "amountMaxCents": { "type": "integer" }, "currency": { "type": "string" } } } } }, "HealthStatus": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "CountryRef": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO-3166 alpha-2 or region code (e.g. EU, GLOBAL)" }, "name": { "type": "string" } }, "required": [ "code", "name" ] }, "FiatCollectionMethod": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "currency": { "type": "string", "description": "ISO-4217" }, "country": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "slug", "label", "currency", "country", "kind" ] }, "CryptoCollectionMethod": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "asset": { "type": "string" }, "network": { "type": "string" } }, "required": [ "slug", "label", "asset", "network" ] }, "PayoutMethod": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "kind": { "type": "string" } }, "required": [ "slug", "label", "country", "currency", "kind" ] }, "ApprovedCatalog": { "type": "object", "properties": { "fiatCollection": { "type": "array", "items": { "type": "string" } }, "cryptoCollection": { "type": "array", "items": { "type": "string" } }, "payouts": { "type": "array", "items": { "type": "string" } } }, "required": [ "fiatCollection", "cryptoCollection", "payouts" ] }, "CryptoWalletChainSupport": { "type": "object", "properties": { "chain": { "type": "string", "description": "Lower-cased Bridge chain name (e.g. base, ethereum, solana)." }, "label": { "type": "string", "description": "Pretty chain label for the picker." }, "currencies": { "type": "array", "items": { "type": "string" }, "description": "Upper-cased asset codes the account may receive on this chain." } }, "required": [ "chain", "label", "currencies" ] }, "PayoutsCatalog": { "type": "object", "properties": { "countries": { "type": "array", "items": { "$ref": "#/components/schemas/CountryRef" } }, "fiatCollection": { "type": "array", "items": { "$ref": "#/components/schemas/FiatCollectionMethod" } }, "cryptoCollection": { "type": "array", "items": { "$ref": "#/components/schemas/CryptoCollectionMethod" } }, "payouts": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutMethod" } }, "cryptoWalletSupport": { "type": "array", "items": { "$ref": "#/components/schemas/CryptoWalletChainSupport" }, "description": "Per-chain support matrix for the New Crypto Collection Wallet picker." }, "approved": { "$ref": "#/components/schemas/ApprovedCatalog" } }, "required": [ "countries", "fiatCollection", "cryptoCollection", "payouts", "cryptoWalletSupport", "approved" ] }, "OnChainRegistration": { "type": "object", "properties": { "onChainId": { "type": "string" }, "onChainRegistry": { "type": "string" }, "onChainTxHash": { "type": "string" }, "ownerEoa": { "type": "string" } }, "required": [ "onChainId", "onChainRegistry", "onChainTxHash", "ownerEoa" ] }, "ActivityEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "entityType": { "type": "string", "enum": [ "account", "principal", "agent" ] }, "entityId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "txHash": { "type": "string", "nullable": true }, "registryAddress": { "type": "string", "nullable": true }, "createdBy": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityType", "entityId", "eventType", "payload", "createdAt" ] }, "ActivityFeed": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "events" ] }, "AgentPhone": { "type": "object", "properties": { "sessionId": { "type": "string", "nullable": true }, "phoneNumberE164": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "description": "Mirrors AgentSIM session status: active|completed|expired|failed" }, "provisionedAt": { "type": "string", "format": "date-time", "nullable": true }, "agentSimAgentId": { "type": "string", "nullable": true, "description": "AgentSIM-side consumer identifier (distinct from our internal agent.id and the per-rental sessionId)." } }, "required": [ "sessionId", "phoneNumberE164", "country", "status", "provisionedAt", "agentSimAgentId" ] }, "AgentOtp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string" }, "agentSimAgentId": { "type": "string", "nullable": true, "description": "AgentSIM-side consumer identifier captured at insert time." }, "otpCode": { "type": "string" }, "senderRaw": { "type": "string" }, "senderInferred": { "type": "string", "nullable": true }, "messageBody": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "sessionId", "agentSimAgentId", "otpCode", "senderRaw", "senderInferred", "messageBody", "receivedAt" ] }, "AgentOtpFeed": { "type": "object", "properties": { "otps": { "type": "array", "items": { "$ref": "#/components/schemas/AgentOtp" } }, "nextCursor": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "otps", "nextCursor" ] }, "AccountOtp": { "allOf": [ { "$ref": "#/components/schemas/AgentOtp" }, { "type": "object", "properties": { "agentName": { "type": "string" } }, "required": [ "agentName" ] } ] }, "AccountOtpFeed": { "type": "object", "properties": { "otps": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOtp" } }, "nextCursor": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "otps", "nextCursor" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] }, "PayoutPreflightInput": { "type": "object", "properties": { "capability": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "country": { "type": "string" }, "recipientName": { "type": "string" }, "recipientEmail": { "type": "string" }, "paymentData": { "type": "object", "additionalProperties": true }, "beneficiary": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "capability", "amount", "currency" ] }, "SendPayoutInput": { "allOf": [ { "$ref": "#/components/schemas/PayoutPreflightInput" }, { "type": "object", "properties": { "runPreflight": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 }, "confirmationToken": { "type": "string", "description": "Required on the second call when amount ≥ $10k." } }, "required": [ "idempotencyKey" ] } ] }, "PayoutIntent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "principalId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid", "nullable": true }, "capability": { "type": "string" }, "amount": { "type": "string", "description": "Decimal string" }, "currency": { "type": "string" }, "country": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "submitted", "completed", "failed", "returned", "cancelled", "dead_letter" ] }, "externalId": { "type": "string", "nullable": true }, "paymentData": { "type": "object", "additionalProperties": true }, "beneficiary": { "type": "object", "additionalProperties": true, "nullable": true }, "fees": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "object", "additionalProperties": true, "nullable": true }, "ledgerTraceId": { "type": "string", "format": "uuid", "nullable": true }, "idempotencyKey": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "requestId", "accountId", "principalId", "capability", "amount", "currency", "status", "paymentData", "idempotencyKey", "createdAt", "updatedAt" ] }, "PayoutIntentFeed": { "type": "object", "properties": { "intents": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutIntent" } }, "nextCursor": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "intents", "nextCursor" ] }, "SendPayoutOk": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "ok" ] }, "intent": { "$ref": "#/components/schemas/PayoutIntent" }, "replayed": { "type": "boolean" } }, "required": [ "step", "intent" ] }, "SendPayoutConfirm": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "confirm" ] }, "confirmationToken": { "type": "string" }, "summary": { "type": "object", "properties": { "capability": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "recipientName": { "type": "string", "nullable": true }, "recipientEmail": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "threshold": { "type": "number" } }, "required": [ "capability", "amount", "currency", "threshold" ] } }, "required": [ "step", "confirmationToken", "summary" ] }, "SendPayoutPreflightFailed": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "preflight_failed" ] }, "preview": { "type": "object", "additionalProperties": true } }, "required": [ "step", "preview" ] }, "SendPayoutResponse": { "oneOf": [ { "$ref": "#/components/schemas/SendPayoutOk" }, { "$ref": "#/components/schemas/SendPayoutConfirm" }, { "$ref": "#/components/schemas/SendPayoutPreflightFailed" } ], "discriminator": { "propertyName": "step", "mapping": { "ok": "#/components/schemas/SendPayoutOk", "confirm": "#/components/schemas/SendPayoutConfirm", "preflight_failed": "#/components/schemas/SendPayoutPreflightFailed" } } }, "InboxRef": { "type": "object", "properties": { "inboxId": { "type": "string" }, "address": { "type": "string" } }, "required": [ "inboxId", "address" ] }, "InboxProvisionResponse": { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/InboxRef" }, "created": { "type": "boolean" } }, "required": [ "inbox", "created" ] }, "InboxThread": { "type": "object", "properties": { "threadId": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "preview": { "type": "string", "nullable": true }, "participants": { "type": "array", "items": { "type": "string" } }, "messageCount": { "type": "integer" }, "unreadCount": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "threadId", "participants", "messageCount", "unreadCount" ] }, "InboxMessage": { "type": "object", "properties": { "messageId": { "type": "string" }, "threadId": { "type": "string" }, "from": { "type": "string", "nullable": true }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "nullable": true }, "preview": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "html": { "type": "string", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] } }, "required": [ "messageId", "threadId", "to", "cc", "bcc", "direction" ] }, "InboxThreadDetail": { "allOf": [ { "$ref": "#/components/schemas/InboxThread" }, { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessage" } } }, "required": [ "messages" ] } ] }, "InboxThreadList": { "type": "object", "properties": { "inbox": { "oneOf": [ { "$ref": "#/components/schemas/InboxRef" }, { "type": "null" } ] }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/InboxThread" } }, "nextPageToken": { "type": "string", "nullable": true } }, "required": [ "threads" ] }, "InboxThreadDetailResponse": { "type": "object", "properties": { "inbox": { "$ref": "#/components/schemas/InboxRef" }, "thread": { "$ref": "#/components/schemas/InboxThreadDetail" } }, "required": [ "inbox", "thread" ] }, "SendInboxMessageInput": { "type": "object", "properties": { "to": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "email" } }, "subject": { "type": "string", "minLength": 1, "maxLength": 998 }, "text": { "type": "string" }, "html": { "type": "string" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "to", "subject" ] }, "CardReloadResult": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string", "nullable": true }, "newBalance": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "availableBalance": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "transactionId": { "type": "string", "nullable": true } }, "required": [ "amount", "currency" ] }, "CardReloadResponse": { "type": "object", "properties": { "resource": { "type": "object", "additionalProperties": true }, "reload": { "$ref": "#/components/schemas/CardReloadResult" } }, "required": [ "resource", "reload" ] }, "CardSummaryResponse": { "type": "object", "properties": { "resource": { "type": "object", "additionalProperties": true }, "card": { "type": "object", "additionalProperties": true } }, "required": [ "resource", "card" ] }, "CardLoad": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "transactionId": { "type": "string" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "currency": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "newBalance": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } }, "SendInboxMessageResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "messageId": { "type": "string" }, "threadId": { "type": "string" } }, "required": [ "ok", "messageId", "threadId" ] } } }, "externalDocs": { "description": "Documentation", "url": "https://agentwallet.ai/docs" } }