{ "openapi": "3.1.0", "info": { "title": "Cloaked Server API", "description": "REST API for managing stealth accounts, generating payment addresses, and relaying transactions. Authenticate with Sign-In with Ethereum (SIWE) to obtain a JWT, then pass it as a Bearer token to account-scoped endpoints.", "version": "1.0.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Pass a JWT token (from SIWE authentication) or an API key as a Bearer token. The server auto-detects the format." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key for retrying one exact mutation. Reusing the same key for the same account, HTTP operation, and request body returns the stored response for 24 hours. This protects ordinary retries but is not an exactly-once guarantee." } }, "schemas": {} }, "paths": { "/relayer/details": { "get": { "operationId": "relayerDetails", "tags": [ "Relayer" ], "description": "Get relayer fee info for a given chain and asset", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": true, "description": "Chain ID" }, { "schema": { "type": "string" }, "in": "query", "name": "assetAddress", "required": true, "description": "Asset address" } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeBPS": { "type": "string" }, "feeReceiverAddress": { "type": "string" }, "chainId": { "type": "number" }, "assetAddress": { "type": "string" }, "minWithdrawAmount": { "type": "string" }, "maxGasPrice": { "type": "string" } }, "required": [ "feeBPS", "feeReceiverAddress", "chainId", "assetAddress", "minWithdrawAmount", "maxGasPrice" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/relayer/quote": { "post": { "operationId": "relayerQuote", "tags": [ "Relayer" ], "description": "Get a fee commitment for relaying a privacy pool withdrawal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "chainId": { "description": "Chain ID", "type": "number" }, "amount": { "description": "Withdrawal amount in smallest token unit", "type": "string" }, "asset": { "description": "Asset address", "type": "string" }, "recipient": { "description": "Recipient address", "type": "string" }, "extraGas": { "description": "Fund recipient with gas", "type": "boolean" } }, "required": [ "chainId", "amount", "asset", "recipient" ] } } }, "required": true }, "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "baseFeeBPS": { "type": "string" }, "feeBPS": { "type": "string" }, "gasPrice": { "type": "string" }, "feeCommitment": { "type": "object", "properties": { "expiration": { "type": "number" }, "asset": { "type": "string" }, "withdrawalData": { "type": "string" }, "signedRelayerCommitment": { "type": "string" }, "extraGas": { "type": "boolean" }, "amount": { "type": "string" } }, "required": [ "expiration", "asset", "withdrawalData", "signedRelayerCommitment", "extraGas", "amount" ] }, "detail": { "type": "object", "properties": { "relayTxCost": { "type": "object", "properties": { "gas": { "type": "string" }, "eth": { "type": "string" } }, "required": [ "gas", "eth" ] }, "extraGasFundAmount": { "type": "object", "properties": { "gas": { "type": "string" }, "eth": { "type": "string" } }, "required": [ "gas", "eth" ] }, "extraGasTxCost": { "type": "object", "properties": { "gas": { "type": "string" }, "eth": { "type": "string" } }, "required": [ "gas", "eth" ] } }, "required": [ "relayTxCost" ] } }, "required": [ "baseFeeBPS", "feeBPS", "gasPrice", "feeCommitment", "detail" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/relayer/request": { "post": { "operationId": "relayerRequest", "tags": [ "Relayer" ], "description": "Submit a privacy pool withdrawal for relay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "withdrawal": { "type": "object", "properties": { "processooor": { "type": "string" }, "data": { "type": "string" } }, "required": [ "processooor", "data" ] }, "proof": { "type": "object", "properties": { "pi_a": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "string" } }, "pi_b": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string" } } }, "pi_c": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "string" } }, "protocol": { "type": "string", "enum": [ "groth16" ] }, "curve": { "type": "string", "enum": [ "bn128" ] } }, "required": [ "pi_a", "pi_b", "pi_c", "protocol", "curve" ] }, "publicSignals": { "minItems": 8, "maxItems": 8, "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "chainId": { "type": "number" }, "feeCommitment": { "type": "object", "properties": { "expiration": { "type": "number" }, "asset": { "type": "string" }, "withdrawalData": { "type": "string" }, "signedRelayerCommitment": { "type": "string" }, "extraGas": { "type": "boolean" }, "amount": { "type": "string" } }, "required": [ "expiration", "asset", "withdrawalData", "signedRelayerCommitment", "extraGas", "amount" ] } }, "required": [ "withdrawal", "proof", "publicSignals", "scope", "chainId", "feeCommitment" ] } } }, "required": true }, "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "txHash": { "type": "string" }, "error": { "type": "string" }, "timestamp": { "type": "number" }, "requestId": { "type": "string" } }, "required": [ "success", "timestamp", "requestId" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/.well-known/hpke-public-key": { "get": { "operationId": "getHpkePublicKey", "tags": [ "Authentication" ], "description": "Retrieve the server's HPKE public key. Clients must encrypt stealth key material with this key before submitting it during account creation or signer enrollment.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "example": "0x...", "type": "string" }, "publicKeyBase64": { "example": "...", "type": "string" }, "format": { "example": "hex", "type": "string" }, "kem": { "example": "X25519-HKDF-SHA256", "type": "string" }, "aead": { "example": "AES-128-GCM", "type": "string" } }, "required": [ "publicKey", "publicKeyBase64", "format", "kem", "aead" ] } } } } } } }, "/v1/.well-known/quote-signer-public-key": { "get": { "operationId": "getQuoteSignerPublicKey", "tags": [ "Transact" ], "description": "Retrieve the server's P-256 ECDSA public key so clients can verify that quote responses were authentically signed by the server and haven't been tampered with.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "example": "04...", "type": "string" }, "format": { "example": "hex", "type": "string" }, "curve": { "example": "P-256", "type": "string" }, "algorithm": { "example": "ECDSA", "type": "string" } }, "required": [ "publicKey", "format", "curve", "algorithm" ] } } } } } } }, "/v1/subdomain/check": { "get": { "operationId": "checkSubdomainAvailability", "tags": [ "Account Management" ], "description": "Check whether a subdomain name is available for registration. Public endpoint — no authentication required. Use before calling setSubdomain to avoid conflicts.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "name", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "inviteCode", "required": false } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "taken" ] }, { "type": "string", "enum": [ "blocked" ] } ] } }, "required": [ "available" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/nonce": { "get": { "operationId": "getNonce", "tags": [ "Authentication" ], "description": "Generate a one-time nonce tied to the given address. This is the first step of Sign-In with Ethereum (SIWE) — the nonce must be included in the SIWE message passed to verifySignin. Nonces expire after 5 minutes.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "address", "required": true, "description": "The auth address to tie the nonce to. This must be the address derived from your private spending key (i.e. `privateKeyToAccount(p_spend).address`), not your connected wallet address." } ], "security": [], "responses": { "200": { "description": "Random nonce string", "content": { "application/json": { "schema": { "type": "string", "description": "Random nonce string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 20 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/verify": { "post": { "operationId": "verifySignin", "tags": [ "Authentication" ], "description": "Complete Sign-In with Ethereum by submitting the signed SIWE message. Returns a JWT session token and the associated accountId if the address already has an account, or null if the user still needs to register.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "message": { "description": "SIWE message string", "type": "string" }, "signature": { "description": "Signature from wallet", "type": "string" }, "authType": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "Optional lowercase snake_case auth mechanism label, e.g. passkey_prf or wallet_pin.", "type": "string" } }, "required": [ "message", "signature" ] } } }, "required": true }, "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "example": true, "type": "boolean" }, "address": { "example": "0x...", "type": "string" }, "token": { "description": "JWT authentication token", "type": "string" }, "accountId": { "description": "Account ID if user is registered, null otherwise", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keyAccessMethod": { "anyOf": [ { "type": "string", "enum": [ "passkey_prf" ] }, { "type": "string", "enum": [ "wallet_pin" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "ok", "address", "token", "accountId", "keyAccessMethod" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unprocessable Entity", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNPROCESSABLE_ENTITY", "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 10 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/extension-authorizations": { "post": { "operationId": "createExtensionAuthorization", "tags": [ "Authentication" ], "description": "Issue a short-lived OAuth authorization code to an allowed browser-extension public client. Authorization Code with S256 PKCE is mandatory.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "response_type": { "type": "string", "enum": [ "code" ] }, "client_id": { "pattern": "^[a-p]{32}$", "type": "string" }, "redirect_uri": { "minLength": 1, "maxLength": 512, "format": "uri", "type": "string" }, "state": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "code_challenge": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "wallet_address": { "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" } }, "required": [ "response_type", "client_id", "redirect_uri", "state", "code_challenge", "code_challenge_method" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "state": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "account_id": { "format": "uuid", "type": "string" }, "expires_in": { "type": "number", "enum": [ 300 ] } }, "required": [ "code", "state", "account_id", "expires_in" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 10 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/oauth/token": { "post": { "operationId": "exchangeExtensionAuthorizationCode", "tags": [ "Authentication" ], "description": "Exchange a one-use OAuth authorization code using the S256 PKCE verifier held by the packaged extension.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ] }, "code": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "client_id": { "pattern": "^[a-p]{32}$", "type": "string" }, "redirect_uri": { "minLength": 1, "maxLength": 512, "format": "uri", "type": "string" }, "code_verifier": { "pattern": "^[A-Za-z0-9._~-]{43,128}$", "type": "string" } }, "required": [ "grant_type", "code", "client_id", "redirect_uri", "code_verifier" ] } } }, "required": true }, "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "number", "enum": [ 604800 ] }, "account_id": { "format": "uuid", "type": "string" }, "auth_method": { "anyOf": [ { "type": "string", "enum": [ "passkey" ] }, { "type": "string", "enum": [ "walletPin" ] } ] }, "wallet_address": { "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "account_id" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 10 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/logout": { "post": { "operationId": "logout", "tags": [ "Authentication" ], "description": "Clear the server-side cache for the authenticated user. JWT tokens are stateless, so the client should also discard the token. Auth is optional — unauthenticated calls succeed without clearing any cache.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "example": true, "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/v1/supported-chains": { "get": { "operationId": "listSupportedChains", "tags": [ "Balance & Activity" ], "description": "List every chain the platform supports, including explorer URLs, logo base names, and testnet/mainnet mapping. Use to populate chain pickers or build explorer links.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "chainId": { "type": "number" }, "isTestnet": { "type": "boolean" }, "explorerUrl": { "type": "string" }, "explorerTxPath": { "type": "string" }, "mainnetChainId": { "type": "number" }, "logoBaseName": { "type": "string" }, "isSquareLogo": { "type": "boolean" } }, "required": [ "name", "chainId", "isTestnet", "explorerUrl", "explorerTxPath", "mainnetChainId", "logoBaseName", "isSquareLogo" ] } } } } } } } }, "/v1/supported-pools": { "get": { "operationId": "listSupportedPools", "tags": [ "Transact" ], "description": "List privacy pools available to the authenticated user, including pool contract addresses, accepted tokens, deposit limits, and ASP (Association Set Provider) details. Feature-flagged pools are only included when the flag is enabled for the account.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "provider": { "type": "string", "enum": [ "privacy-pools" ] }, "poolAddress": { "example": "0x...", "type": "string" }, "chainId": { "example": 1, "type": "number" }, "chainName": { "example": "Ethereum", "type": "string" }, "token": { "example": "0x...", "type": "string" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "logoUrl": { "example": "https://...", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minDeposit": { "example": "10000000000000000", "type": "string" }, "maxDeposit": { "example": "100000000000000000000", "type": "string" }, "totalBalance": { "description": "Total pool balance in smallest unit (stringified bigint), or null if unavailable", "example": "2659000000000000000000", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "description": "Pool scope as a stringified bigint — keccak256(poolAddress, chainId, asset) mod SNARK_SCALAR_FIELD. Used by the client to derive deposit precommitments.", "example": "12345678901234567890", "type": "string" }, "asp": { "type": "object", "properties": { "name": { "example": "0xbow", "type": "string" }, "policyUrl": { "example": "https://0xbow.io/policy", "type": "string" } }, "required": [ "name", "policyUrl" ] }, "maxRelayFeeBPS": { "description": "On-chain contract maximum for relayFeeBPS on withdrawals", "example": 1000, "type": "number" }, "withdrawalFeePerProofWei": { "description": "Estimated gas cost in wei for relaying one ZK proof withdrawal (stringified bigint). Refreshed periodically.", "example": "95000000000000", "type": "string" } }, "required": [ "provider", "poolAddress", "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "minDeposit", "maxDeposit", "totalBalance", "scope", "asp", "maxRelayFeeBPS", "withdrawalFeePerProofWei" ] }, { "additionalProperties": false, "type": "object", "properties": { "provider": { "type": "string", "enum": [ "privacy-boost" ] }, "poolAddress": { "example": "0x...", "type": "string" }, "chainId": { "example": 1, "type": "number" }, "chainName": { "example": "Ethereum", "type": "string" }, "token": { "example": "0x...", "type": "string" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "logoUrl": { "example": "https://...", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minDeposit": { "example": "10000000000000000", "type": "string" }, "maxDeposit": { "example": "100000000000000000000", "type": "string" }, "totalBalance": { "description": "Total pool balance in smallest unit (stringified bigint), or null if unavailable", "example": "2659000000000000000000", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "provider", "poolAddress", "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "minDeposit", "maxDeposit", "totalBalance" ] } ] } } } } } } } }, "/v1/token-catalog": { "get": { "operationId": "getTokenCatalog", "tags": [ "Balance & Activity" ], "description": "Public, read-only access to the existing supported token catalog, pinned symbols for the swap picker, and testnet-to-mainnet chain-ID mapping. This endpoint never discovers tokens or persists token data.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": false }, { "schema": { "minimum": 1, "maximum": 1000, "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "include", "required": false, "description": "Comma-separated optional enrichments. Supported values: market,sources." } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] } }, "pinnedSymbols": { "type": "array", "items": { "type": "string" } }, "testnetToMainnet": { "type": "object", "additionalProperties": { "type": "number" } }, "nextCursor": { "type": "string" } }, "required": [ "tokens", "pinnedSymbols", "testnetToMainnet" ] } } } } } } }, "/v1/tokens/popular": { "get": { "operationId": "getPopularTokens", "tags": [ "Balance & Activity" ], "description": "Allowed catalog tokens in CoinGecko six-hour trending order, with safety-status checks from Uniswap’s full default list or volume rankings. Trending includes six-hour pool price changes. Transfer fees do not exclude a token. Trending does not require a top-50 volume rank. Falls back to checked Uniswap top-50 volume results. Empty when checks are unavailable or the network is disabled.", "parameters": [ { "schema": { "minimum": 1, "type": "integer" }, "in": "query", "name": "chainId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "coingecko-trending" ] }, { "type": "string", "enum": [ "uniswap-popular" ] } ] }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } }, "change6h": { "type": "object", "properties": { "percentage": { "type": "number" }, "observedAt": { "format": "date-time", "type": "string" } }, "required": [ "percentage", "observedAt" ] }, "change24h": { "type": "object", "properties": { "percentage": { "type": "number" }, "observedAt": { "format": "date-time", "type": "string" } }, "required": [ "percentage", "observedAt" ] } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] } } }, "required": [ "tokens" ] } } } } } } }, "/v1/token-lookup": { "get": { "operationId": "lookupToken", "tags": [ "Balance & Activity" ], "description": "Look up token metadata by contract address for an authenticated account. Checks cached sources first, then may query trusted token providers and on-chain ERC-20 metadata and persist newly discovered sources.", "parameters": [ { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": true }, { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "include", "required": false, "description": "Comma-separated optional enrichments. Supported values: market,sources." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/referrals/availability": { "get": { "operationId": "getReferralAvailability", "tags": [ "Account Management" ], "description": "Check whether referral links may be accepted or generated for the current request location.", "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/referrals/by-name/{name}/resolve": { "get": { "operationId": "resolveReferralName", "tags": [ "Account Management" ], "description": "Resolve a permanent clkd.eth name to its active referral code, public identity, and current terms.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "path", "name": "name", "required": true } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "pattern": "^[0-9a-f]{24}$", "type": "string" }, "referrerName": { "maxLength": 255, "type": "string" }, "referrerShareBps": { "minimum": 1, "maximum": 10000, "type": "integer" }, "referredDiscountBps": { "minimum": 0, "maximum": 10000, "type": "integer" }, "earningDurationDays": { "minimum": 1, "type": "integer" }, "minimumRewardUsdCents": { "minimum": 0, "type": "integer" } }, "required": [ "code", "referrerName", "referrerShareBps", "referredDiscountBps", "earningDurationDays", "minimumRewardUsdCents" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/referrals/{code}/preview": { "get": { "operationId": "getReferralPreview", "tags": [ "Account Management" ], "description": "Return the public display name and current terms for an eligible referral link.", "parameters": [ { "schema": { "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "in": "path", "name": "code", "required": true } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "referrerName": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "referrerShareBps": { "minimum": 1, "maximum": 10000, "type": "integer" }, "referredDiscountBps": { "minimum": 0, "maximum": 10000, "type": "integer" }, "earningDurationDays": { "minimum": 1, "type": "integer" }, "minimumRewardUsdCents": { "minimum": 0, "type": "integer" } }, "required": [ "referrerName", "referrerShareBps", "referredDiscountBps", "earningDurationDays", "minimumRewardUsdCents" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/addresses/apps": { "get": { "operationId": "getAddressHistoryApps", "tags": [ "Account Management" ], "description": "List apps successfully used by this account on enabled networks. Includes all owned addresses, independent of address filters and pagination. Requires dapp-connect.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "type": "string" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } } }, "required": [ "apps" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/addresses": { "get": { "operationId": "getAddressHistory", "tags": [ "Account Management" ], "description": "List generated addresses and recorded activity on networks enabled for this account. Likely spam activity and non-displayable token balances are excluded using the existing activity token policy. Filters apply before pagination: each page contains up to limit matching addresses. total counts all generated addresses, including those outside the filter. No recorded activity does not guarantee an address has never been shared or used.", "parameters": [ { "schema": { "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" }, "in": "query", "name": "address", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "recorded" ] } ] }, "in": "query", "name": "activity", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasBalance", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "usedWithApps", "required": false }, { "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "maxLength": 255, "type": "string" } }, "in": "query", "name": "appOrigins", "required": false, "description": "Match successful use of any selected app hostname before pagination. Repeat this parameter for multiple apps. Requires dapp-connect." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeSummary", "required": false, "description": "Include page-scoped activity counts, holdings and up to three recent app summaries. A summary may be omitted if display metadata is unavailable." }, { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "maxLength": 512, "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "generationContext": { "anyOf": [ { "type": "string", "enum": [ "external" ] }, { "type": "string", "enum": [ "fund-movement" ] }, { "type": "null" } ] }, "address": { "type": "string" }, "nonce": { "type": "string" }, "createdAt": { "type": "string" }, "hasActivity": { "type": "boolean" }, "activityCount": { "minimum": 0, "description": "Activity entries with likely spam hidden on enabled networks. Included with includeSummary; pending activity is indicated separately.", "type": "integer" }, "hasPendingActivity": { "type": "boolean" }, "hasBalance": { "type": "boolean" }, "summary": { "type": "object", "properties": { "balances": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string" }, "amount": { "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "type": "integer" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usdAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "chainId", "token", "amount", "tokenSymbol", "decimals", "logoUrl", "usdAmount" ] } }, "totalUsdBalance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "usedApps": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "type": "string" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } } }, "required": [ "balances", "totalUsdBalance", "usedApps" ] } }, "required": [ "generationContext", "address", "nonce", "createdAt", "hasActivity", "hasPendingActivity", "hasBalance" ] } }, "total": { "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkedChainIds": { "type": "array", "items": { "type": "integer" } } }, "required": [ "items", "total", "nextCursor", "checkedChainIds" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/": { "post": { "operationId": "createAccount", "tags": [ "Account Management" ], "description": "Register a new account by submitting HPKE-encrypted key material. The caller must already have a JWT from the SIWE sign-in flow, which proves ownership of the Ethereum address. The server decrypts and stores the keys, enabling payment address generation for this account. Requires an invite code when gated access is enabled. Returns the new accountId, or indicates if the address already has an account.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ciphertext": { "description": "Base64-encoded encrypted payload", "type": "string" }, "encapsulatedKey": { "description": "Base64-encoded HPKE encapsulated key", "type": "string" }, "inviteCode": { "description": "Invite code for gated access", "type": "string" }, "onboardingExperimentId": { "format": "uuid", "type": "string" }, "experimentKey": { "maxLength": 64, "type": "string" }, "variantKey": { "maxLength": 64, "type": "string" }, "referralCode": { "maxLength": 64, "type": "string" } }, "required": [ "ciphertext", "encapsulatedKey" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "description": "Created account ID (null if already existed)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alreadyExisted": { "type": "boolean" }, "referralApplied": { "description": "Whether the newly created account was atomically attributed to the supplied referral", "type": "boolean" } }, "required": [ "accountId", "alreadyExisted", "referralApplied" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}": { "get": { "operationId": "getAccount", "tags": [ "Account Management" ], "description": "Retrieve account metadata including the owner address, registration status, and ENS subdomain. Useful for determining onboarding state (e.g., whether the user still needs to claim a subdomain).", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isRegistered": { "type": "boolean" }, "keyAccessMethod": { "description": "Server-recorded key-access method for the authenticated signer. 'unknown' preserves legacy and API-key sessions.", "anyOf": [ { "type": "string", "enum": [ "passkey_prf" ] }, { "type": "string", "enum": [ "wallet_pin" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "createdAt": { "description": "Timestamp when the account was created.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "subdomain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "encryptedCustomEnsName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "activationOfferClaimExpiresAt": { "description": "Timestamp when the new-user activation offer can no longer be claimed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "lastConsumedNonce": { "description": "Last consumed stealth address nonce (0-indexed). null if no addresses generated yet.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cloakie": { "anyOf": [ { "type": "object", "properties": { "active": { "type": "boolean" }, "deposits": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "depositAddress": { "type": "string" } }, "required": [ "tokenId", "imageUrl", "depositAddress" ] } } }, "required": [ "active", "deposits" ] }, { "type": "null" } ] }, "hasPoolDeposits": { "description": "True if the account has any pool commitment rows. Used to trigger eager pool balance discovery at login.", "type": "boolean" }, "dismissedProfilePrompts": { "description": "Profile prompts permanently dismissed for this account across browsers and devices.", "type": "array", "items": { "enum": [ "backup-reminder", "custom-ens", "referrals" ], "type": "string" } } }, "required": [ "accountId", "address", "isRegistered", "keyAccessMethod", "createdAt", "subdomain", "encryptedCustomEnsName", "activationOfferClaimExpiresAt", "lastConsumedNonce", "dismissedProfilePrompts" ] } } } } } } }, "/v1/accounts/{accountId}/provenance-address-tags": { "get": { "operationId": "listProvenanceAddressTags", "tags": [ "Transact" ], "description": "List encrypted display tag payload ciphertexts for owned addresses.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tagPayloadCiphertext": { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "type": "string" }, "tagPayloadUpdatedAt": { "format": "date-time", "type": "string" } }, "required": [ "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt" ] } } }, "required": [ "tags" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/provenance-address-tags/{address}": { "put": { "operationId": "setProvenanceAddressTags", "tags": [ "Transact" ], "description": "Set or clear encrypted display tag payload ciphertext for an owned address.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "New encrypted display tag payload ciphertext. Null clears the tags.", "type": "string" }, { "type": "null" } ] } }, "required": [ "tagPayloadCiphertext" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true, "description": "Owned address whose private tags should be updated" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt" ] } }, "required": [ "tag" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/dapp-addresses": { "get": { "operationId": "getDappAddresses", "tags": [ "Account Management" ], "description": "List addresses used in successful onchain browser-extension dApp actions.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "association" ] }, { "type": "string", "enum": [ "address" ] } ] }, "in": "query", "name": "paginateBy", "required": false, "description": "Page by individual associations (default), or by addresses with all their apps." }, { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "app": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "type": "string" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "address", "app", "lastUsedAt" ] } }, "hasMore": { "type": "boolean" } }, "required": [ "items", "hasMore" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/address-ownership": { "get": { "operationId": "getAddressOwnership", "tags": [ "Account Management" ], "description": "Check whether an Ethereum address belongs to the authenticated account.", "parameters": [ { "schema": { "minLength": 42, "maxLength": 42, "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "owned": { "type": "boolean" } }, "required": [ "owned" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/address-balances": { "get": { "operationId": "getAddressBalances", "tags": [ "Transact" ], "description": "List address-held balances grouped by address, enriched with token metadata, dApp usage, receive history, and provenance metadata.", "parameters": [ { "schema": { "default": true, "type": "boolean" }, "in": "query", "name": "includeHistory", "required": false, "description": "Include past dApp usage, receive summaries, and provenance. Set false for current balances only; current dApp identity and address ordering are preserved." }, { "schema": { "anyOf": [ { "description": "Select addresses with unlocked funds that may fund a transaction, excluding addresses reserved for active Cloakie deposits. Use available for the fundable amount; amount, usdAmount, and totalUsdBalance continue to include locked funds. Requires chainId and token.", "type": "string", "enum": [ "funding" ] }, { "description": "Select active owned addresses that previously received a successful private withdrawal, ordered by the latest withdrawal time. Requires visible, available funds on an enabled network. Eligibility is applied before pagination.", "type": "string", "enum": [ "connect-private" ] } ] }, "in": "query", "name": "purpose", "required": false }, { "schema": { "minLength": 42, "maxLength": 42, "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": false, "description": "Return balances for this exact owned address only" }, { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": false, "description": "Filter balances to one chain ID" }, { "schema": { "type": "string" }, "in": "query", "name": "token", "required": false, "description": "Filter balances to one token address" }, { "schema": { "type": "string" }, "in": "query", "name": "dappOrigin", "required": false, "description": "Filter recently-used addresses by this dApp origin" }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "Max addresses to return (up to 100). Defaults to 50 for connect-private; omit to return all for other purposes." }, { "schema": { "minimum": 0, "maximum": 9007199254740991, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "dapp": { "anyOf": [ { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "type": "string" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recognitionStatus": { "anyOf": [ { "type": "string", "enum": [ "recognized" ] }, { "type": "string", "enum": [ "blocked" ] }, { "type": "string", "enum": [ "unrecognized" ] } ] }, "verified": { "type": "boolean" } }, "required": [ "origin", "displayName", "iconUrl", "recognitionStatus", "verified" ] }, { "type": "null" } ] }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "nonce": { "type": "string" }, "lastPrivatelyFundedAt": { "description": "Latest successful private withdrawal into this address. Populated only for purpose=connect-private; otherwise null.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "usedOrigins": { "type": "array", "items": { "type": "string" } }, "usedApps": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "type": "string" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "recentlyUsedByDapp": { "type": "boolean" }, "totalUsdBalance": { "description": "USD value of all returned balances, including unlocked and locked outputs", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "balances": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "chainName": { "type": "string" }, "token": { "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Total raw amount in smallest unit, including unlocked and locked outputs", "type": "string" }, "available": { "description": "Currently unlocked raw amount in smallest unit", "type": "string" }, "pending": { "description": "Currently locked raw amount in smallest unit", "type": "string" }, "usdAmount": { "description": "USD value of the total amount, including unlocked and locked outputs", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceStale": { "type": "boolean" }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "listed": { "description": "Whether the token is visible in the account token catalog", "type": "boolean" }, "idCount": { "description": "Number of output IDs represented by this balance; funding mode counts only unlocked outputs", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct priced/displayable chain-token assets seen for this address", "type": "number" }, "chainCount": { "description": "Distinct networks with priced/displayable assets at this address", "type": "number" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "chainName": { "type": "string" }, "token": { "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Total raw amount in smallest unit, including unlocked and locked outputs", "type": "string" }, "usdAmount": { "description": "USD value of the total amount, including unlocked and locked outputs", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "amount", "usdAmount", "pricePerToken", "priceObservedAt" ] } } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount", "assets" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "lastReceivedAt": { "description": "Most recent included output. In funding mode this considers only unlocked outputs.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "amount", "available", "pending", "usdAmount", "pricePerToken", "priceStale", "priceObservedAt", "listed", "idCount", "lastReceivedAt" ] } } }, "required": [ "address", "nonce", "lastPrivatelyFundedAt", "totalUsdBalance", "balances" ] } }, "total": { "description": "Total number of matching addresses before pagination", "type": "number" } }, "required": [ "provenanceLabelGroups", "dapp", "addresses", "total" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/tokens": { "get": { "operationId": "listAccountTokens", "tags": [ "Account Management" ], "description": "List active token imports for the authenticated account.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "include", "required": false, "description": "Comma-separated optional enrichments. Supported values: market,sources." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] } } }, "required": [ "tokens" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "post": { "operationId": "importAccountToken", "tags": [ "Account Management" ], "description": "Import an allowed canonical token for the authenticated account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "required": [ "chainId", "address" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "include", "required": false, "description": "Comma-separated optional enrichments. Supported values: market,sources." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] } }, "required": [ "token" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 10 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/tokens/{chainId}/{address}": { "get": { "operationId": "getAccountTokenDetail", "tags": [ "Account Management" ], "description": "Return canonical token metadata and this account’s balance for one token. Use include=market,sources to attach current market data and provider provenance.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "include", "required": false, "description": "Comma-separated optional enrichments. Supported values: market,sources." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "type": "string" }, "in": "path", "name": "chainId", "required": true, "description": "Chain ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true, "description": "Token contract address" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "number" }, "chainId": { "type": "number" }, "logoURI": { "type": "string" }, "isClanker": { "type": "boolean" }, "visibility": { "type": "string" }, "metadataSource": { "type": "string" }, "market": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "providerAssetId": { "type": "string" }, "vsCurrency": { "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCap": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapRank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fullyDilutedValuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalVolume": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "high24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "low24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChange24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketCapChangePercentage24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "circulatingSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSupply": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "athDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlChangePercentage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "atlDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceObservedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "marketObservedAt": { "format": "date-time", "type": "string" }, "fetchedAt": { "format": "date-time", "description": "Deprecated alias of marketObservedAt.", "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "provider", "providerAssetId", "vsCurrency", "price", "marketCap", "marketCapRank", "fullyDilutedValuation", "totalVolume", "high24h", "low24h", "priceChange24h", "priceChangePercentage24h", "marketCapChange24h", "marketCapChangePercentage24h", "circulatingSupply", "totalSupply", "maxSupply", "ath", "athChangePercentage", "athDate", "atl", "atlChangePercentage", "atlDate", "providerUpdatedAt", "priceObservedAt", "marketObservedAt", "fetchedAt", "stale" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "logoUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "firstSeenAt": { "type": "string" }, "lastSeenAt": { "type": "string" } }, "required": [ "source", "sourceId", "firstSeenAt", "lastSeenAt" ] } } }, "required": [ "address", "symbol", "name", "decimals", "chainId" ] }, "balance": { "description": "Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.", "type": "object", "properties": { "chainId": { "example": 8453, "description": "Chain ID where this token resides", "type": "number" }, "chainName": { "example": "Base", "description": "Human-readable chain name", "type": "string" }, "token": { "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Token contract address (EIP-55 checksummed)", "type": "string" }, "tokenSymbol": { "example": "USDC", "description": "Token ticker symbol", "type": "string" }, "decimals": { "example": 6, "description": "Token decimal places", "type": "number" }, "logoUrl": { "example": "https://assets.coingecko.com/coins/images/6319/small/usdc.png", "description": "Token logo URL, or null if unavailable", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visible": { "description": "Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.", "type": "object", "properties": { "available": { "example": "1000000", "description": "Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)", "type": "string" }, "pending": { "example": "500000", "description": "Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pending" ] }, "incognito": { "description": "Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.", "type": "object", "properties": { "pooled": { "description": "Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.", "type": "object", "properties": { "available": { "example": "750000", "description": "Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)", "type": "string" }, "pendingApproval": { "example": "250000", "description": "Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)", "type": "string" }, "pendingWithdrawal": { "example": "500000", "description": "ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)", "type": "string" }, "declined": { "example": "0", "description": "Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pendingApproval", "pendingWithdrawal", "declined" ] } }, "required": [ "pooled" ] }, "usdAmount": { "example": 1.5, "description": "Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "example": 2000.42, "description": "USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceStale": { "example": false, "description": "True when the price is older than the display refresh target but still usable", "type": "boolean" }, "priceObservedAt": { "description": "Oldest source observation used to produce pricePerToken. Null when pricing is unavailable.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "spam": { "example": false, "description": "True if the token is flagged as potential spam or a phishing token", "type": "boolean" } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "visible", "incognito", "usdAmount", "pricePerToken", "priceStale", "priceObservedAt", "spam" ] } }, "required": [ "token", "balance" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/payment-address": { "post": { "operationId": "createPaymentAddress", "tags": [ "Receive" ], "description": "Derive a one-time payment address so a sender can transfer tokens to this account without revealing the recipient on-chain.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": {} } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "header", "name": "idempotency-key", "required": false, "description": "Client-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours." } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "nonce": { "description": "Nonce used for derivation (stringified bigint)", "type": "string" }, "reused": { "description": "True when the daily limit is reached and a previously-issued address is served instead of a fresh one.", "type": "boolean" }, "limitResetsAt": { "description": "ISO timestamp (next UTC midnight) when fresh addresses become available again. Present only when reused is true.", "type": "string" } }, "required": [ "address", "nonce" ] } } } } } } }, "/v1/accounts/{accountId}/destination-avatar": { "get": { "operationId": "resolveSendDestinationAvatar", "tags": [ "Send" ], "description": "Resolve the public avatar URL for a supported send destination name. Returns null when the destination is not a supported name or no public avatar is configured.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "query", "name": "destinationAddress", "required": true, "description": "Destination address or supported Ethereum name entered in the send form." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "url" ] }, { "type": "string", "enum": [ "inline" ] } ] }, "in": "query", "name": "format", "required": false, "description": "Use inline for a size-limited raster image data URL fetched by the server. Unsupported or unavailable images return null. Defaults to url." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "avatarUrl" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/recipient-address-kind": { "get": { "operationId": "classifySendRecipientAddress", "tags": [ "Send" ], "description": "Classify a send recipient address and report whether it resembles a previously trusted destination.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": true, "description": "Chain ID selected in the send form." }, { "schema": { "minLength": 42, "maxLength": 42, "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": true, "description": "Raw 0x recipient address to inspect." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string", "enum": [ "eoa" ] }, { "type": "string", "enum": [ "eip7702" ] }, { "type": "string", "enum": [ "contract" ] } ] }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] } }, "required": [ "kind" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/quote": { "post": { "operationId": "createQuote", "tags": [ "Transact" ], "description": "Unified quote endpoint. For type=send: reserves balances and returns signing data. For type=swap: reserves balances and returns swap intents via Uniswap.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "title": "SendQuoteRequest", "anyOf": [ { "additionalProperties": false, "title": "SingleSendQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "send" ] }, "feePaymentRecovery": { "type": "boolean", "enum": [ true ] }, "feePaymentToken": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "recoveryAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "chainId": { "description": "Chain ID (must support Porto)", "type": "number" }, "token": { "description": "Token address (0x...)", "type": "string" }, "amount": { "description": "Amount in smallest unit (stringified bigint). Required unless maxSend is true.", "type": "string" }, "decimals": { "description": "Token decimals (integer 0-255)", "type": "number" }, "destinationAddress": { "description": "Destination address (0x... or supported Ethereum name)", "type": "string" }, "acknowledgedAddressPoisoningMatch": { "additionalProperties": false, "type": "object", "properties": { "recipientAddress": { "minLength": 42, "maxLength": 42, "type": "string" }, "matchedAddress": { "minLength": 42, "maxLength": 42, "type": "string" } }, "required": [ "recipientAddress", "matchedAddress" ] }, "excludedSpendableAddresses": { "description": "Addresses excluded from funding on the source chain. Automatic selection still chooses among the remaining addresses.", "minItems": 1, "maxItems": 50, "uniqueItems": true, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "spendableAddresses": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Optional address-held funding sources to use exactly for this quote.", "type": "string" } }, "singleAddress": { "description": "Single-address mode: pin the transaction to this owned address — inputs are selected only from it and any change stays on it. Cannot be combined with spendableAddresses.", "type": "string" }, "maxSend": { "description": "When true, server computes the maximum sendable amount. Amount field is ignored.", "type": "boolean" }, "executionSimulation": { "description": "Require the exact signed send intents to execute successfully in simulation.", "type": "string", "enum": [ "required" ] }, "ttl": { "description": "Lock TTL in seconds (default: 86400, max: 86400)", "minimum": 1, "maximum": 86400, "type": "number" } }, "required": [ "type", "chainId", "token", "decimals", "destinationAddress" ] }, { "additionalProperties": false, "title": "BatchSendQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "send" ] }, "chainId": { "description": "Chain ID (must support Porto)", "type": "number" }, "destinationAddress": { "description": "Destination address (0x... or supported Ethereum name)", "type": "string" }, "acknowledgedAddressPoisoningMatch": { "additionalProperties": false, "type": "object", "properties": { "recipientAddress": { "minLength": 42, "maxLength": 42, "type": "string" }, "matchedAddress": { "minLength": 42, "maxLength": 42, "type": "string" } }, "required": [ "recipientAddress", "matchedAddress" ] }, "assets": { "type": "array", "items": { "additionalProperties": false, "title": "BatchSendAsset", "type": "object", "properties": { "chainId": { "description": "Optional per-asset chain ID. When present it must match the top-level chainId.", "type": "number" }, "token": { "description": "Token address (0x...)", "type": "string" }, "amount": { "description": "Amount in smallest unit (stringified bigint).", "type": "string" }, "decimals": { "description": "Token decimals (integer 0-255)", "type": "number" }, "spendableAddresses": { "type": "array", "items": { "description": "Address-held funding sources to use exactly for this asset.", "type": "string" } } }, "required": [ "token", "amount", "decimals" ] } }, "executionSimulation": { "description": "Require every exact signed send intent to execute successfully in simulation.", "type": "string", "enum": [ "required" ] }, "ttl": { "description": "Lock TTL in seconds (default: 86400, max: 86400)", "minimum": 1, "maximum": 86400, "type": "number" } }, "required": [ "type", "chainId", "destinationAddress", "assets" ] } ] }, { "additionalProperties": false, "title": "SwapQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "swap" ] }, "chainId": { "description": "Chain ID", "type": "number" }, "tokenIn": { "description": "Token address being sold", "type": "string" }, "tokenInDecimals": { "minimum": 0, "maximum": 255, "description": "Decimals used by the client to calculate amountIn; must match resolved token metadata.", "type": "integer" }, "tokenOut": { "description": "Token address being bought", "type": "string" }, "tokenOutDecimals": { "minimum": 0, "maximum": 255, "description": "Output decimals expected by the client for review validation.", "type": "integer" }, "amountIn": { "description": "Amount to swap in smallest unit (stringified bigint). Required unless maxSend is true.", "type": "string" }, "slippageMode": { "description": "Slippage selection mode. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.", "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Manual slippage tolerance in basis points (e.g. 50 = 0.5%, max: 500 = 5%)", "minimum": 1, "maximum": 500, "type": "number" }, "tokenOutChainId": { "description": "Destination chain ID for cross-chain swaps", "type": "number" }, "maxSend": { "description": "When true, server computes max swappable amount. amountIn is ignored.", "type": "boolean" }, "excludedSpendableAddresses": { "description": "Addresses excluded from funding on the source chain. Automatic selection still chooses among the remaining addresses.", "minItems": 1, "maxItems": 50, "uniqueItems": true, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "spendableAddresses": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Optional address-held funding sources to use exactly for this swap.", "type": "string" } }, "singleAddress": { "description": "Single-address mode: pin the swap to this owned address — inputs are selected only from it, the output (and bridge destination) is delivered to it, and any change stays on it. Cannot be combined with spendableAddresses.", "type": "string" }, "destinationAddress": { "minLength": 1, "maxLength": 255, "description": "Optional address or supported Ethereum name that receives the swap/bridge output. Omit to receive into a fresh Cloaked address.", "type": "string" }, "acknowledgedContractRecipient": { "minLength": 42, "maxLength": 42, "description": "Exact resolved contract address acknowledged by the user. Required only when the destination resolves to a smart contract.", "type": "string" }, "acknowledgedAddressPoisoningMatch": { "additionalProperties": false, "type": "object", "properties": { "recipientAddress": { "minLength": 42, "maxLength": 42, "type": "string" }, "matchedAddress": { "minLength": 42, "maxLength": 42, "type": "string" } }, "required": [ "recipientAddress", "matchedAddress" ] } }, "required": [ "type", "chainId", "tokenIn", "tokenOut" ] }, { "additionalProperties": false, "title": "ConvertRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "pool-deposit" ] }, "chainId": { "description": "Chain ID where the privacy pool lives", "type": "number" }, "token": { "description": "Token address to deposit (0x...)", "type": "string" }, "amount": { "description": "Deposit amount in smallest unit (stringified bigint). Required unless maxSend is true.", "type": "string" }, "decimals": { "description": "Token decimals (0-255)", "minimum": 0, "maximum": 255, "type": "number" }, "maxSend": { "description": "When true, server computes max deposit amount atomically. Amount field is ignored.", "type": "boolean" }, "spendableAddresses": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Optional address-held funding sources to use exactly for this pool deposit.", "type": "string" } }, "singleAddress": { "description": "Single-address mode: pin the deposit to this owned address — inputs are selected only from it and any change stays on it. Cannot be combined with spendableAddresses.", "type": "string" }, "precommitment": { "description": "Precommitment hash (stringified bigint) binding the deposit secrets without revealing them", "type": "string" }, "nullifierHash": { "description": "Hash of the commitment nullifier (stringified bigint). Lets the server cross-reference on-chain spends.", "type": "string" }, "depositIndex": { "description": "Client-derived deposit index used for precommitment derivation. Falls back to server-computed index if omitted.", "minimum": 0, "type": "number" }, "reservation": { "description": "Signed reservation token returned by the pool-deposit reservation endpoint.", "maxLength": 131072, "type": "string" } }, "required": [ "type", "chainId", "token", "decimals", "precommitment", "nullifierHash" ] }, { "additionalProperties": false, "title": "PoolWithdrawQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "pool-withdraw" ] }, "chainId": { "description": "Chain ID where the privacy pool lives", "type": "number" }, "token": { "description": "Token address to withdraw (0x...)", "type": "string" }, "amount": { "description": "Amount in smallest unit (stringified bigint)", "type": "string" }, "amountMode": { "description": "Whether amount is the gross pool withdrawal amount or exact post-fee receive amount.", "anyOf": [ { "type": "string", "enum": [ "withdrawal" ] }, { "type": "string", "enum": [ "receive" ] } ] }, "maxSend": { "description": "Whether this quote should spend the selected commitments as a max flow.", "type": "boolean" }, "decimals": { "description": "Token decimals (0-255)", "minimum": 0, "maximum": 255, "type": "number" }, "destinationAddress": { "description": "Recipient of the withdrawn funds: your own active clkd.eth name for a self-withdrawal (a fresh owned address is minted), or any 0x address / ENS / clkd.eth name for an incognito send to a third party.", "type": "string" }, "acknowledgedAddressPoisoningMatch": { "additionalProperties": false, "type": "object", "properties": { "recipientAddress": { "minLength": 42, "maxLength": 42, "type": "string" }, "matchedAddress": { "minLength": 42, "maxLength": 42, "type": "string" } }, "required": [ "recipientAddress", "matchedAddress" ] }, "commitmentId": { "format": "uuid", "description": "Incognito balance commitment id to withdraw from.", "type": "string" } }, "required": [ "type", "chainId", "token", "amount", "decimals", "destinationAddress", "commitmentId" ] }, { "additionalProperties": false, "title": "ConversionRecoverRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "pool-recover" ] }, "chainId": { "description": "Chain ID where the privacy pool lives", "type": "number" }, "token": { "description": "Token address (0x...)", "type": "string" }, "commitmentId": { "description": "DB ID of the declined commitment to recover", "type": "string" } }, "required": [ "type", "chainId", "token", "commitmentId" ] }, { "additionalProperties": false, "title": "BoostDepositQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "boost-deposit" ] }, "chainId": { "description": "Chain ID where the Privacy Boost pool lives", "type": "number" }, "token": { "description": "Source token to deposit (native sentinel for ETH)", "type": "string" }, "amount": { "description": "Deposit amount in smallest unit (stringified bigint)", "type": "string" }, "decimals": { "description": "Token decimals (0-255)", "minimum": 0, "maximum": 255, "type": "number" } }, "required": [ "type", "chainId", "token", "amount", "decimals" ] }, { "title": "DappCallRequest", "anyOf": [ { "additionalProperties": false, "title": "DappCallQuoteRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-call" ] }, "feePaymentRecovery": { "type": "boolean", "enum": [ true ] }, "chainId": { "description": "Chain ID to execute on", "type": "number" }, "address": { "description": "Stealth address to execute from (0x...)", "type": "string" }, "dappOrigin": { "description": "Origin hostname of the dApp (e.g. app.uniswap.org)", "maxLength": 255, "type": "string" }, "dappMetadata": { "additionalProperties": false, "type": "object", "properties": { "displayName": { "maxLength": 255, "type": "string" }, "iconUrl": { "maxLength": 2048, "type": "string" }, "iconSource": { "maxLength": 64, "type": "string" } } }, "calls": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "to": { "description": "Target contract address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "value": { "description": "ETH value in wei (hex or decimal string)", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "type": "string" }, "data": { "description": "Calldata (hex string)", "pattern": "^0x[a-fA-F0-9]*$", "type": "string" } }, "required": [ "to", "value", "data" ] } }, "feePaymentToken": { "description": "Token selected by the user to reimburse relay fees for this dApp call. Native token sentinel or ERC20 address.", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "feePaymentCandidates": { "maxItems": 12, "uniqueItems": true, "description": "Bounded fee-token candidates from the connected address. The server independently verifies every entry.", "type": "array", "items": { "description": "Token selected by the user to reimburse relay fees for this dApp call. Native token sentinel or ERC20 address.", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "prepareAddress": { "type": "boolean", "enum": [ false ] } }, "required": [ "type", "chainId", "address", "calls", "feePaymentToken" ] }, { "additionalProperties": false, "title": "DappAddressPreparationRequest", "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-call" ] }, "feePaymentRecovery": { "type": "boolean", "enum": [ true ] }, "chainId": { "description": "Chain ID to execute on", "type": "number" }, "address": { "description": "Stealth address to execute from (0x...)", "type": "string" }, "dappOrigin": { "description": "Origin hostname of the dApp (e.g. app.uniswap.org)", "maxLength": 255, "type": "string" }, "dappMetadata": { "additionalProperties": false, "type": "object", "properties": { "displayName": { "maxLength": 255, "type": "string" }, "iconUrl": { "maxLength": 2048, "type": "string" }, "iconSource": { "maxLength": 64, "type": "string" } } }, "calls": { "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "to": { "description": "Target contract address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "value": { "description": "ETH value in wei (hex or decimal string)", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "type": "string" }, "data": { "description": "Calldata (hex string)", "pattern": "^0x[a-fA-F0-9]*$", "type": "string" } }, "required": [ "to", "value", "data" ] } }, "prepareAddress": { "description": "Create a fee-paying no-op intent that installs the EIP-7702 account code before connecting to a dapp.", "type": "boolean", "enum": [ true ] }, "feePaymentToken": { "description": "Token selected by the user to reimburse relay fees for this dApp call. Native token sentinel or ERC20 address.", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "required": [ "type", "chainId", "address", "calls", "prepareAddress" ] } ] } ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "header", "name": "idempotency-key", "required": false, "description": "Client-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "title": "SwapQuoteResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "signingReview": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "intents": { "type": "array", "items": { "type": "object", "properties": { "userActionCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "simulationCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "calldataCaveats": { "type": "array", "items": { "type": "object", "properties": { "callIndex": { "minimum": 0, "type": "integer" }, "kind": { "type": "string", "enum": [ "provider-calldata-suffix" ] }, "policyVersion": { "type": "number", "enum": [ 1 ] }, "verifier": { "minLength": 1, "maxLength": 128, "type": "string" }, "suffixLength": { "minimum": 1, "maximum": 1024, "type": "integer" }, "canonicalCalldataHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "suffixHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "callIndex", "kind", "policyVersion", "verifier", "suffixLength", "canonicalCalldataHash", "suffixHash" ] } } }, "required": [ "userActionCallIndices" ] } } }, "required": [ "version", "intents" ] }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "expectedOutput": { "type": "string" }, "minimumOutput": { "type": "string" }, "outputToken": { "type": "string" }, "inputDecimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "outputDecimals": { "type": "number" }, "outputSymbol": { "type": "string" }, "outputRecipient": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] }, "outputRecipientOwned": { "description": "Server-verified assertion that outputRecipient belongs to the authenticated Cloaked account.", "type": "boolean" }, "recoveryRecipient": { "type": "string" }, "slippageMode": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Effective slippage tolerance in basis points. Omitted when the route has no explicit slippage value.", "type": "number" }, "requestedSlippageBps": { "type": "number" }, "routing": { "type": "string" }, "bridgeProvider": { "anyOf": [ { "type": "string", "enum": [ "uniswap" ] }, { "type": "string", "enum": [ "across" ] } ] }, "refresh": { "type": "object", "properties": { "after": { "description": "ISO timestamp after which an active review may request a replacement quote.", "type": "string" }, "sessionExpiresAt": { "description": "Fixed ISO expiry for the review session. Refreshing never extends this deadline.", "type": "string" } }, "required": [ "after", "sessionExpiresAt" ] }, "protocolFeeBps": { "type": "number" }, "protocolFeeAmount": { "type": "string" }, "amountIn": { "type": "string" }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "priceImpact": { "type": "number" }, "estimatedFillTimeMs": { "type": "number" }, "fillDeadline": { "type": "number" }, "planId": { "description": "Bridge routing plan identifier from Across protocol, present only for cross-chain (CHAINED) quotes", "type": "string" }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "expectedOutput", "minimumOutput", "outputToken", "outputDecimals", "outputSymbol", "outputRecipient", "outputRecipientOwned", "slippageMode", "routing", "protocolFeeBps", "protocolFeeAmount", "amountIn", "fees" ] }, { "title": "ConversionRecoverResponse", "type": "object", "properties": { "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "poolAddress": { "type": "string" }, "commitment": { "type": "object", "properties": { "id": { "type": "string" }, "depositIndex": { "type": "number" }, "withdrawalIndex": { "type": "number" }, "commitment": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "id", "depositIndex", "withdrawalIndex", "commitment", "label", "value" ] }, "depositorAddress": { "description": "Stealth address that made the original deposit (msg.sender for ragequit).", "type": "string" } }, "required": [ "quoteId", "expiresAt", "signature", "poolAddress", "commitment", "depositorAddress" ] }, { "title": "IncognitoSendResponse", "type": "object", "properties": { "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "poolAddress": { "type": "string" }, "resolvedDestination": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] }, "destinationAddressNonce": { "description": "Nonce used to derive the generated self-withdraw destination address.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destinationAvatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selfSend": { "type": "boolean" }, "feeRecipient": { "description": "Address to receive relay fees", "type": "string" }, "relayFeeBPS": { "description": "Definitive relay fee BPS for this set of commitments. Client bakes into each proof.", "type": "number" }, "feePerProof": { "description": "Estimated fee per ZK proof relay in the pool token units (stringified bigint)", "type": "string" }, "maxRelayFeeBPS": { "description": "On-chain contract maximum for relayFeeBPS", "type": "number" }, "withdrawalAmount": { "description": "Gross amount proven to the pool before relay fees are deducted.", "type": "string" }, "receiveAmount": { "description": "Amount delivered to the recipient after relay fees are deducted.", "type": "string" }, "amountMode": { "description": "Whether amount was quoted as a gross withdrawal amount or exact post-fee receive amount.", "anyOf": [ { "type": "string", "enum": [ "withdrawal" ] }, { "type": "string", "enum": [ "receive" ] } ] }, "commitments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "depositIndex": { "type": "number" }, "withdrawalIndex": { "type": "number" }, "commitment": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "withdrawalAmount": { "type": "string" }, "pooledSince": { "description": "ISO timestamp when the ASP approved this commitment (entered the anonymity set)", "type": "string" } }, "required": [ "id", "depositIndex", "withdrawalIndex", "commitment", "label", "value", "withdrawalAmount", "pooledSince" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "quoteId", "expiresAt", "signature", "poolAddress", "resolvedDestination", "destinationAvatarUrl", "selfSend", "feeRecipient", "relayFeeBPS", "feePerProof", "maxRelayFeeBPS", "withdrawalAmount", "receiveAmount", "amountMode", "commitments", "fees" ] }, { "title": "ConvertResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "poolAddress": { "type": "string" }, "depositIndex": { "type": "number" }, "grossAmount": { "description": "Total ETH sent to entrypoint (amount + vetting fee)", "type": "string" }, "feeAmount": { "description": "Vetting fee deducted by the pool", "type": "string" }, "feeBps": { "description": "Vetting fee in basis points", "type": "number" }, "netPoolValue": { "description": "Net value credited to the pool commitment", "type": "string" }, "cloakedFeeBps": { "description": "Cloaked protocol fee rate in basis points", "type": "number" }, "cloakedFlatFee": { "description": "Flat fee floor in wei for the Cloaked deposit fee", "type": "string" }, "cloakieFeeMode": { "description": "Legacy fee mode: flat when the Cloaked deposit fee is waived, otherwise standard", "anyOf": [ { "type": "string", "enum": [ "flat" ] }, { "type": "string", "enum": [ "standard" ] } ] }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "poolAddress", "depositIndex", "grossAmount", "feeAmount", "feeBps", "netPoolValue", "cloakedFeeBps", "cloakedFlatFee", "cloakieFeeMode", "fees" ] }, { "title": "BatchSendQuoteResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "signingReview": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "intents": { "type": "array", "items": { "type": "object", "properties": { "userActionCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "simulationCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "calldataCaveats": { "type": "array", "items": { "type": "object", "properties": { "callIndex": { "minimum": 0, "type": "integer" }, "kind": { "type": "string", "enum": [ "provider-calldata-suffix" ] }, "policyVersion": { "type": "number", "enum": [ 1 ] }, "verifier": { "minLength": 1, "maxLength": 128, "type": "string" }, "suffixLength": { "minimum": 1, "maximum": 1024, "type": "integer" }, "canonicalCalldataHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "suffixHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "callIndex", "kind", "policyVersion", "verifier", "suffixLength", "canonicalCalldataHash", "suffixHash" ] } } }, "required": [ "userActionCallIndices" ] } } }, "required": [ "version", "intents" ] }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "resolvedDestination": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] }, "destinationAvatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selfSend": { "type": "boolean" }, "executionSimulation": { "type": "string", "enum": [ "passed" ] }, "sourceAssets": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "decimals": { "type": "number" }, "symbol": { "type": "string" }, "amount": { "type": "string" }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "chainId", "token", "decimals", "symbol", "amount", "fees" ] } }, "feeTotals": { "type": "object", "properties": { "totalUsdAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "totalUsdAmount" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "resolvedDestination", "destinationAvatarUrl", "selfSend", "sourceAssets", "feeTotals" ] }, { "title": "SendQuoteResponse", "type": "object", "properties": { "feePayment": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "payer": { "type": "string" }, "maximum": { "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "payer", "maximum" ] }, "recipientAmount": { "description": "Simulated recipient increase in the sent token, at quote time", "type": "string" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "signingReview": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "intents": { "type": "array", "items": { "type": "object", "properties": { "userActionCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "simulationCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "calldataCaveats": { "type": "array", "items": { "type": "object", "properties": { "callIndex": { "minimum": 0, "type": "integer" }, "kind": { "type": "string", "enum": [ "provider-calldata-suffix" ] }, "policyVersion": { "type": "number", "enum": [ 1 ] }, "verifier": { "minLength": 1, "maxLength": 128, "type": "string" }, "suffixLength": { "minimum": 1, "maximum": 1024, "type": "integer" }, "canonicalCalldataHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "suffixHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "callIndex", "kind", "policyVersion", "verifier", "suffixLength", "canonicalCalldataHash", "suffixHash" ] } } }, "required": [ "userActionCallIndices" ] } } }, "required": [ "version", "intents" ] }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "resolvedDestination": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] }, "destinationAvatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "description": "Source amount selected for the send, in smallest units", "type": "string" }, "selfSend": { "type": "boolean" }, "executionSimulation": { "type": "string", "enum": [ "passed" ] }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "resolvedDestination", "destinationAvatarUrl", "sourceAmount", "selfSend", "fees" ] }, { "title": "BoostDepositQuoteResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "submissionSignature": { "description": "Server authorization binding this experimental quote to its exact submission", "type": "string" }, "poolAddress": { "type": "string" }, "depositAmount": { "description": "Shielded deposit amount in the token smallest unit", "type": "string" }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "submissionSignature", "poolAddress", "depositAmount", "fees" ] }, { "title": "DappAddressPreparedResponse", "type": "object", "properties": { "prepared": { "type": "boolean", "enum": [ true ] }, "address": { "type": "string" }, "chainId": { "type": "number" }, "expectedCode": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "prepared", "address", "chainId", "expectedCode", "signature" ] }, { "title": "DappCallQuoteResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] }, "feePayment": { "type": "object", "properties": { "token": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "available": { "type": "string" }, "maxSpendable": { "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable" ] }, "feePaymentOptions": { "maxItems": 12, "description": "Funded, priced fee tokens that passed the complete dapp action-and-fee simulation", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "minLength": 1, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "maxSpendable": { "pattern": "^[0-9]+$", "type": "string" }, "feeEstimate": { "pattern": "^[0-9]+$", "description": "Safely simulated maximum execution fee in the token smallest unit", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable", "feeEstimate" ] } }, "feePaymentChoices": { "maxItems": 12, "description": "Same-address, active-chain fee assets. Selecting an asset requires a fresh quote; this inventory does not establish fee affordability.", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] } }, "executionSimulation": { "type": "string", "enum": [ "passed" ] }, "calldataCaveats": { "type": "array", "items": { "type": "object", "properties": { "callIndex": { "minimum": 0, "type": "integer" }, "kind": { "type": "string", "enum": [ "provider-calldata-suffix" ] }, "policyVersion": { "type": "number", "enum": [ 1 ] }, "verifier": { "minLength": 1, "maxLength": 128, "type": "string" }, "suffixLength": { "minimum": 1, "maximum": 1024, "type": "integer" }, "canonicalCalldataHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "suffixHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "callIndex", "kind", "policyVersion", "verifier", "suffixLength", "canonicalCalldataHash", "suffixHash" ] } }, "preparationRequired": { "type": "boolean", "enum": [ true ] }, "expectedCode": { "type": "string" } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "fees", "feePayment", "executionSimulation" ] }, { "title": "GroupSendQuoteResponse", "type": "object", "properties": { "quoteId": { "type": "string" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "resolvedDestination": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] } }, "required": [ "quoteId", "intents", "expiresAt", "signature", "resolvedDestination" ] } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "feePaymentRecovery": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "payment-unverified" ] }, { "type": "string", "enum": [ "insufficient-fee-balance" ] }, { "type": "string", "enum": [ "network-unavailable" ] } ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "type": "string" }, "selected": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] }, "choices": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] } }, "funding": { "type": "object", "properties": { "available": { "type": "string" }, "required": { "type": "string" }, "shortfall": { "type": "string" }, "blockNumber": { "type": "string" }, "observedAt": { "type": "string" } }, "required": [ "available", "required", "shortfall", "blockNumber", "observedAt" ] }, "resolvedDestination": { "type": "string" }, "maxSendAmountBeforeFee": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "reason", "chainId", "address", "selected", "choices" ] }, "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" }, "requestedSlippageBps": { "minimum": 1, "maximum": 500, "description": "Manual slippage submitted by the client, in basis points", "example": 100, "type": "integer" }, "recommendedSlippageBps": { "minimum": 1, "maximum": 9999, "description": "Minimum slippage recommended by the route provider, in basis points", "example": 500, "type": "integer" }, "feePaymentOptions": { "maxItems": 12, "description": "Funded, priced fee tokens that passed the complete dapp action-and-fee simulation", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "minLength": 1, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "maxSpendable": { "pattern": "^[0-9]+$", "type": "string" }, "feeEstimate": { "pattern": "^[0-9]+$", "description": "Safely simulated maximum execution fee in the token smallest unit", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable", "feeEstimate" ] } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "feePaymentRecovery": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "payment-unverified" ] }, { "type": "string", "enum": [ "insufficient-fee-balance" ] }, { "type": "string", "enum": [ "network-unavailable" ] } ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "type": "string" }, "selected": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] }, "choices": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] } }, "funding": { "type": "object", "properties": { "available": { "type": "string" }, "required": { "type": "string" }, "shortfall": { "type": "string" }, "blockNumber": { "type": "string" }, "observedAt": { "type": "string" } }, "required": [ "available", "required", "shortfall", "blockNumber", "observedAt" ] }, "resolvedDestination": { "type": "string" }, "maxSendAmountBeforeFee": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "reason", "chainId", "address", "selected", "choices" ] }, "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" }, "requestedSlippageBps": { "minimum": 1, "maximum": 500, "description": "Manual slippage submitted by the client, in basis points", "example": 100, "type": "integer" }, "recommendedSlippageBps": { "minimum": 1, "maximum": 9999, "description": "Minimum slippage recommended by the route provider, in basis points", "example": 500, "type": "integer" }, "feePaymentOptions": { "maxItems": 12, "description": "Funded, priced fee tokens that passed the complete dapp action-and-fee simulation", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "minLength": 1, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "maxSpendable": { "pattern": "^[0-9]+$", "type": "string" }, "feeEstimate": { "pattern": "^[0-9]+$", "description": "Safely simulated maximum execution fee in the token smallest unit", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable", "feeEstimate" ] } } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } ] } } } } } } }, "/v1/accounts/{accountId}/quotes/{quoteId}/refresh": { "post": { "operationId": "refreshQuote", "tags": [ "Transact" ], "description": "Atomically replace a refreshable active quote while preserving its original review-session deadline and locked funds.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "quote": { "description": "Exact signed quote returned by the server. Its registered refresh builder validates the quote shape after signature verification." } }, "required": [ "quote" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "quoteId", "required": true, "description": "Current quote ID" }, { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "Required retry key for this exact refresh request." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "title": "SwapQuoteResponse", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "signingReview": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "intents": { "type": "array", "items": { "type": "object", "properties": { "userActionCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "simulationCallIndices": { "type": "array", "items": { "minimum": 0, "type": "integer" } }, "calldataCaveats": { "type": "array", "items": { "type": "object", "properties": { "callIndex": { "minimum": 0, "type": "integer" }, "kind": { "type": "string", "enum": [ "provider-calldata-suffix" ] }, "policyVersion": { "type": "number", "enum": [ 1 ] }, "verifier": { "minLength": 1, "maxLength": 128, "type": "string" }, "suffixLength": { "minimum": 1, "maximum": 1024, "type": "integer" }, "canonicalCalldataHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "suffixHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "callIndex", "kind", "policyVersion", "verifier", "suffixLength", "canonicalCalldataHash", "suffixHash" ] } } }, "required": [ "userActionCallIndices" ] } } }, "required": [ "version", "intents" ] }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "expectedOutput": { "type": "string" }, "minimumOutput": { "type": "string" }, "outputToken": { "type": "string" }, "inputDecimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "outputDecimals": { "type": "number" }, "outputSymbol": { "type": "string" }, "outputRecipient": { "type": "string" }, "addressPoisoningMatch": { "type": "object", "properties": { "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "matchedSuffixCharsCount": { "minimum": 0, "maximum": 40, "type": "integer" }, "source": { "anyOf": [ { "type": "string", "enum": [ "address-book" ] }, { "type": "string", "enum": [ "confirmed-transaction" ] } ] }, "contactName": { "type": "string" } }, "required": [ "matchedAddress", "matchedPrefixCharsCount", "matchedSuffixCharsCount", "source" ] }, "destinationName": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "description": "Normalized destination name resolved for this quote.", "type": "string" }, "service": { "anyOf": [ { "type": "string", "enum": [ "ens" ] }, { "type": "string", "enum": [ "gwei" ] } ] } }, "required": [ "name", "service" ] }, "outputRecipientOwned": { "description": "Server-verified assertion that outputRecipient belongs to the authenticated Cloaked account.", "type": "boolean" }, "recoveryRecipient": { "type": "string" }, "slippageMode": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Effective slippage tolerance in basis points. Omitted when the route has no explicit slippage value.", "type": "number" }, "requestedSlippageBps": { "type": "number" }, "routing": { "type": "string" }, "bridgeProvider": { "anyOf": [ { "type": "string", "enum": [ "uniswap" ] }, { "type": "string", "enum": [ "across" ] } ] }, "refresh": { "type": "object", "properties": { "after": { "description": "ISO timestamp after which an active review may request a replacement quote.", "type": "string" }, "sessionExpiresAt": { "description": "Fixed ISO expiry for the review session. Refreshing never extends this deadline.", "type": "string" } }, "required": [ "after", "sessionExpiresAt" ] }, "protocolFeeBps": { "type": "number" }, "protocolFeeAmount": { "type": "string" }, "amountIn": { "type": "string" }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "priceImpact": { "type": "number" }, "estimatedFillTimeMs": { "type": "number" }, "fillDeadline": { "type": "number" }, "planId": { "description": "Bridge routing plan identifier from Across protocol, present only for cross-chain (CHAINED) quotes", "type": "string" }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "intents", "delegations", "quoteId", "expiresAt", "signature", "expectedOutput", "minimumOutput", "outputToken", "outputDecimals", "outputSymbol", "outputRecipient", "outputRecipientOwned", "slippageMode", "routing", "protocolFeeBps", "protocolFeeAmount", "amountIn", "fees" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/subdomain": { "post": { "operationId": "claimSubdomain", "tags": [ "Account Management" ], "description": "Claim an ENS subdomain (e.g. alice.clkd.eth) for this account so senders can pay via a human-readable name instead of a raw address. Each account may claim one subdomain.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "subdomain": { "description": "Subdomain name (will be normalized and stored as {subdomain}.clkd.eth)", "type": "string" } }, "required": [ "subdomain" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "subdomain": { "type": "string" } }, "required": [ "success", "message", "subdomain" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/subdomain/generate": { "get": { "operationId": "generateSubdomain", "tags": [ "Account Management" ], "description": "Generate a random available subdomain for the user to preview during onboarding. The name is not reserved — call setSubdomain to claim it.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subdomain": { "example": "example-123.clkd.eth", "type": "string" } }, "required": [ "subdomain" ] } } } } } } }, "/v1/accounts/{accountId}/submit": { "post": { "operationId": "submitTransaction", "tags": [ "Transact" ], "description": "Submit client-signed intents and delegations from a quote to relay the transaction on-chain. Validates signatures, checks price slippage, and submits via the server relayer so the user pays no gas directly.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "title": "PortoSubmitRequest", "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] }, "signature": { "type": "string" } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType", "signature" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" }, "signature": { "type": "string" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce", "signature" ] } }, "quoteId": { "description": "Quote ID from quote response", "type": "string" }, "submissionSignature": { "description": "Server authorization required for quotes that do not yet have a persisted transaction intent", "type": "string" }, "walletCallBatch": { "additionalProperties": false, "type": "object", "properties": { "id": { "pattern": "^0x(?:[0-9a-fA-F]{2})+$", "minLength": 4, "maxLength": 8194, "type": "string" }, "origin": { "minLength": 1, "maxLength": 255, "type": "string" } }, "required": [ "origin" ] }, "recoverCalldata": { "description": "Canonical encoded Pool.ragequit(proof) calldata (hex)", "pattern": "^0x[0-9a-fA-F]+$", "maxLength": 2048, "type": "string" } }, "required": [ "intents", "delegations", "quoteId" ] }, { "additionalProperties": false, "title": "PoolWithdrawSubmitRequest", "type": "object", "properties": { "quoteId": { "description": "Quote ID from pool-withdraw quote response", "type": "string" }, "withdrawals": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "commitmentId": { "description": "Pool commitment DB ID", "type": "string" }, "calldata": { "description": "Encoded Entrypoint.relay() calldata (hex)", "type": "string" }, "changeNullifierHash": { "description": "Nullifier hash of the change commitment created by a partial withdrawal (stringified bigint)", "type": "string" } }, "required": [ "commitmentId", "calldata" ] } } }, "required": [ "quoteId", "withdrawals" ] }, { "additionalProperties": false, "title": "ConversionRecoverSubmitRequest", "type": "object", "properties": { "quoteId": { "description": "Quote ID from pool-recover quote response", "type": "string" }, "recoverCalldata": { "description": "Canonical encoded Pool.ragequit(proof) calldata (hex)", "pattern": "^0x[0-9a-fA-F]+$", "maxLength": 2048, "type": "string" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] }, "signature": { "type": "string" } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType", "signature" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" }, "signature": { "type": "string" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce", "signature" ] } } }, "required": [ "quoteId", "recoverCalldata", "intents", "delegations" ] } ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "header", "name": "idempotency-key", "required": false, "description": "Client-generated key for one account, HTTP operation, and exact request body. Reuse it only to retry that same operation; a completed retry returns the stored response. Keys expire after 24 hours." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "quoteId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "walletCallBatchId": { "type": "string" } }, "required": [ "success", "quoteId", "status", "message" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/relay-status/{quoteId}": { "get": { "operationId": "getRelayStatus", "tags": [ "Transact" ], "description": "Get the relay transaction status and hash for a submitted quote.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "type": "string" }, "in": "query", "name": "origin", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "quoteId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "operationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "chainId": { "type": "number" }, "txHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confirmedTxHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confirmedTxHashes": { "type": "array", "items": { "type": "string" } }, "canonicalTxHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "walletStatus": { "type": "number" }, "receipt": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "data": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } } }, "required": [ "address", "data", "topics" ] } }, "status": { "type": "string" }, "blockHash": { "type": "string" }, "blockNumber": { "type": "string" }, "gasUsed": { "type": "string" }, "transactionHash": { "type": "string" } }, "required": [ "logs", "status", "blockHash", "blockNumber", "gasUsed", "transactionHash" ] } }, "required": [ "quoteId", "status", "chainId", "txHash", "confirmedTxHash", "canonicalTxHash", "walletStatus" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/unlock": { "post": { "operationId": "unlockQuote", "tags": [ "Transact" ], "description": "Release the lock held by a quote so the funds become available for a new transaction. Use when the user cancels a send or the client decides not to submit.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "quoteId": { "description": "Quote ID from quote response", "type": "string" } }, "required": [ "quoteId" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/max-spendable": { "post": { "operationId": "getMaxSpendable", "tags": [ "Transact" ], "description": "Calculate the maximum spendable amount for a token, accounting for relay fees, swap gas, and pool fees when applicable. Use this to power the \"max\" button in send, swap, and pool UIs.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "feePaymentRecovery": { "type": "boolean", "enum": [ true ] }, "chainId": { "description": "Chain ID (must support Porto)", "type": "number" }, "token": { "description": "Token address (0x...)", "type": "string" }, "type": { "description": "Transaction type — swap, pool-deposit, and boost-deposit subtract additional gas/service fees", "anyOf": [ { "type": "string", "enum": [ "send" ] }, { "type": "string", "enum": [ "swap" ] }, { "type": "string", "enum": [ "pool-deposit" ] }, { "type": "string", "enum": [ "boost-deposit" ] } ] }, "tokenOut": { "description": "Token address to buy (required for type=swap)", "type": "string" }, "slippageMode": { "description": "Slippage mode for swap max-spendable. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.", "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Manual slippage tolerance in bps (type=swap, 1-500)", "minimum": 1, "maximum": 500, "type": "number" }, "tokenOutChainId": { "description": "Destination chain ID for cross-chain swaps", "type": "number" }, "spendableAddresses": { "description": "Optional address-held funding sources to use exactly for this max calculation.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Selectable spendable address", "type": "string" } }, "excludedSpendableAddresses": { "description": "Addresses excluded from funding on the source chain. Automatic selection still chooses among the remaining addresses.", "minItems": 1, "maxItems": 50, "uniqueItems": true, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "singleAddress": { "description": "Single-address mode: compute the max using only this owned address. Cannot be combined with spendableAddresses.", "type": "string" }, "destinationAddress": { "minLength": 1, "maxLength": 255, "description": "Optional address or supported Ethereum name that receives swap output. Names are resolved only for the final quote.", "type": "string" } }, "required": [ "chainId", "token", "type" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxAmount": { "description": "Maximum spendable amount in smallest unit", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit", "type": "string" }, "feeEstimateUsdAmount": { "description": "USD value of feeEstimate, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spendableCount": { "description": "Number of spendable UTXOs that will be consumed", "type": "number" }, "grossAmount": { "description": "Gross deposit amount including vetting fee (pool-deposit only)", "type": "string" }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee estimate", "type": "string" }, "vetting": { "description": "On-chain vetting fee", "type": "string" }, "deposit": { "description": "Cloaked service fee (0 if waived)", "type": "string" }, "service": { "description": "Vetting + deposit combined", "type": "string" }, "total": { "description": "Network + service total", "type": "string" } }, "required": [ "network", "vetting", "deposit", "service", "total" ] }, "protocolFeeBps": { "description": "Protocol fee rate in bps (swap only)", "type": "number" }, "protocolFeeAmount": { "description": "Protocol fee amount in smallest unit (swap only)", "type": "string" } }, "required": [ "maxAmount", "feeEstimate", "spendableCount" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "feePaymentRecovery": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "payment-unverified" ] }, { "type": "string", "enum": [ "insufficient-fee-balance" ] }, { "type": "string", "enum": [ "network-unavailable" ] } ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "type": "string" }, "selected": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] }, "choices": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] } }, "funding": { "type": "object", "properties": { "available": { "type": "string" }, "required": { "type": "string" }, "shortfall": { "type": "string" }, "blockNumber": { "type": "string" }, "observedAt": { "type": "string" } }, "required": [ "available", "required", "shortfall", "blockNumber", "observedAt" ] }, "resolvedDestination": { "type": "string" }, "maxSendAmountBeforeFee": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "reason", "chainId", "address", "selected", "choices" ] }, "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" }, "requestedSlippageBps": { "minimum": 1, "maximum": 500, "description": "Manual slippage submitted by the client, in basis points", "example": 100, "type": "integer" }, "recommendedSlippageBps": { "minimum": 1, "maximum": 9999, "description": "Minimum slippage recommended by the route provider, in basis points", "example": 500, "type": "integer" }, "feePaymentOptions": { "maxItems": 12, "description": "Funded, priced fee tokens that passed the complete dapp action-and-fee simulation", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "minLength": 1, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "maxSpendable": { "pattern": "^[0-9]+$", "type": "string" }, "feeEstimate": { "pattern": "^[0-9]+$", "description": "Safely simulated maximum execution fee in the token smallest unit", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable", "feeEstimate" ] } } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "feePaymentRecovery": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "payment-unverified" ] }, { "type": "string", "enum": [ "insufficient-fee-balance" ] }, { "type": "string", "enum": [ "network-unavailable" ] } ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "type": "string" }, "selected": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] }, "choices": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available" ] } }, "funding": { "type": "object", "properties": { "available": { "type": "string" }, "required": { "type": "string" }, "shortfall": { "type": "string" }, "blockNumber": { "type": "string" }, "observedAt": { "type": "string" } }, "required": [ "available", "required", "shortfall", "blockNumber", "observedAt" ] }, "resolvedDestination": { "type": "string" }, "maxSendAmountBeforeFee": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "reason", "chainId", "address", "selected", "choices" ] }, "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" }, "requestedSlippageBps": { "minimum": 1, "maximum": 500, "description": "Manual slippage submitted by the client, in basis points", "example": 100, "type": "integer" }, "recommendedSlippageBps": { "minimum": 1, "maximum": 9999, "description": "Minimum slippage recommended by the route provider, in basis points", "example": 500, "type": "integer" }, "feePaymentOptions": { "maxItems": 12, "description": "Funded, priced fee tokens that passed the complete dapp action-and-fee simulation", "type": "array", "items": { "type": "object", "properties": { "token": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "minLength": 1, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "available": { "pattern": "^[0-9]+$", "type": "string" }, "maxSpendable": { "pattern": "^[0-9]+$", "type": "string" }, "feeEstimate": { "pattern": "^[0-9]+$", "description": "Safely simulated maximum execution fee in the token smallest unit", "type": "string" } }, "required": [ "token", "symbol", "decimals", "available", "maxSpendable", "feeEstimate" ] } } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } ] } } } } } } }, "/v1/accounts/{accountId}/pool-deposit-reservations": { "post": { "operationId": "createPoolDepositReservation", "tags": [ "Transact" ], "description": "Reserve funding inputs and return the exact privacy-pool deposit values for review before wallet authentication.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "title": "PoolDepositReservationRequest", "type": "object", "properties": { "chainId": { "description": "Chain ID where the privacy pool lives", "type": "number" }, "token": { "description": "Token address to deposit (0x...)", "type": "string" }, "amount": { "description": "Deposit amount in smallest unit (stringified bigint). Required unless maxSend is true.", "type": "string" }, "decimals": { "description": "Token decimals (0-255)", "minimum": 0, "maximum": 255, "type": "number" }, "maxSend": { "description": "When true, server computes max deposit amount atomically. Amount field is ignored.", "type": "boolean" }, "spendableAddresses": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Optional address-held funding sources to use exactly for this pool deposit.", "type": "string" } }, "singleAddress": { "description": "Single-address mode: pin the deposit to this owned address — inputs are selected only from it and any change stays on it. Cannot be combined with spendableAddresses.", "type": "string" } }, "required": [ "chainId", "token", "decimals" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "description": "Lock ID for cancellation and finalization", "type": "string" }, "expiresAt": { "description": "ISO expiry for the temporary funding lock", "type": "string" }, "reservation": { "description": "Opaque signed token required to finalize this reservation", "type": "string" }, "signature": { "description": "Signature over the complete review response", "type": "string" }, "poolAddress": { "type": "string" }, "grossAmount": { "description": "Total amount sent to the pool entrypoint including vetting fee", "type": "string" }, "feeAmount": { "description": "Vetting fee deducted by the pool", "type": "string" }, "feeBps": { "description": "Vetting fee in basis points", "type": "number" }, "netPoolValue": { "description": "Estimated net value credited to the private pool balance", "type": "string" }, "cloakedFeeBps": { "description": "Cloaked protocol fee rate in basis points", "type": "number" }, "cloakedFlatFee": { "type": "string" }, "cloakieFeeMode": { "anyOf": [ { "type": "string", "enum": [ "flat" ] }, { "type": "string", "enum": [ "standard" ] } ] }, "selectedFundingSources": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "token": { "type": "string" }, "address": { "type": "string" }, "amount": { "description": "Raw selected amount in smallest unit", "type": "string" }, "idCount": { "description": "Number of spendable output IDs represented by this selected funding source", "type": "number" }, "addressSummary": { "type": "object", "properties": { "receiveCount": { "description": "Action-aware inbound receive count. Trusted Cloaked actions that emit multiple transfer logs are counted once.", "type": "number" }, "rawReceiveCount": { "description": "Literal distinct inbound transfer/log count before trusted-action collapsing.", "type": "number" }, "trustedReceiveActionCount": { "description": "Number of Cloaked-managed receive actions collapsed into receiveCount.", "type": "number" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "description": "Distinct chain-token assets seen for this address.", "type": "number" }, "chainCount": { "description": "Distinct networks seen for this address.", "type": "number" } }, "required": [ "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount" ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "chainId", "token", "address", "amount", "idCount", "addressSummary", "provenance" ] } }, "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "fees": { "type": "object", "properties": { "network": { "description": "Gas/relay fee in wei (gas cost only, excludes dust)", "type": "string" }, "dust": { "description": "Residual balance below the dust threshold swept into the relayer payment. Not a gas fee — included in total but not in network.", "type": "string" }, "service": { "description": "Protocol fees in wei (vetting + cloaked, or swap protocol fee)", "type": "string" }, "networkUsdAmount": { "description": "USD value of the network fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalUsdAmount": { "description": "USD value of the total fee, or null when USD pricing is unavailable", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vetting": { "description": "On-chain vetting fee in wei (pool deposits only)", "type": "string" }, "deposit": { "description": "Cloaked deposit fee in wei (pool deposits only)", "type": "string" }, "total": { "description": "Total fees in wei (network + dust + service)", "type": "string" }, "waived": { "description": "True when fees are waived (e.g. Cloakie holder on swaps)", "type": "boolean" } }, "required": [ "network", "service", "total" ] } }, "required": [ "quoteId", "expiresAt", "reservation", "signature", "poolAddress", "grossAmount", "feeAmount", "feeBps", "netPoolValue", "cloakedFeeBps", "cloakedFlatFee", "cloakieFeeMode", "fees" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/swap-preview": { "post": { "operationId": "createSwapPreview", "tags": [ "Transact" ], "description": "Get a swap preview (price discovery) without reserving balances.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "chainId": { "description": "Chain ID", "type": "number" }, "tokenIn": { "description": "Token address being sold", "type": "string" }, "tokenInDecimals": { "minimum": 0, "maximum": 255, "description": "Decimals used by the client to calculate amountIn; must match resolved token metadata.", "type": "integer" }, "tokenOut": { "description": "Token address being bought", "type": "string" }, "tokenOutDecimals": { "minimum": 0, "maximum": 255, "description": "Output decimals expected by the client for review validation.", "type": "integer" }, "amountIn": { "description": "Amount to swap in smallest unit (stringified bigint)", "type": "string" }, "includeFeeEstimate": { "description": "When false, return an indicative provider rate without calldata generation or on-chain gas simulation. Defaults to true.", "type": "boolean" }, "slippageMode": { "description": "Slippage selection mode. auto asks the route provider to calculate slippage; manual uses slippageBps. Responses omit slippageBps when the route has no explicit slippage value.", "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Manual slippage tolerance in basis points (e.g. 50 = 0.5%, max: 500 = 5%)", "minimum": 1, "maximum": 500, "type": "number" }, "tokenOutChainId": { "description": "Destination chain ID for cross-chain swaps", "type": "number" }, "spendableAddresses": { "description": "Optional address-held funding sources to use exactly for this swap preview.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "Selectable spendable address", "type": "string" } }, "excludedSpendableAddresses": { "description": "Addresses excluded from funding on the source chain. Automatic selection still chooses among the remaining addresses.", "minItems": 1, "maxItems": 50, "uniqueItems": true, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "singleAddress": { "description": "Single-address mode: preview using only this owned address. Cannot be combined with spendableAddresses.", "type": "string" }, "destinationAddress": { "minLength": 1, "maxLength": 255, "description": "Optional address or supported Ethereum name that receives swap output. Names are resolved only for the final quote.", "type": "string" } }, "required": [ "chainId", "tokenIn", "tokenOut", "amountIn" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedOutput": { "type": "string" }, "minimumOutput": { "type": "string" }, "outputToken": { "type": "string" }, "inputDecimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "outputDecimals": { "type": "number" }, "outputSymbol": { "type": "string" }, "routing": { "type": "string" }, "slippageMode": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "slippageBps": { "description": "Effective slippage tolerance in basis points. Omitted when the route has no explicit slippage value.", "type": "number" }, "requestedSlippageBps": { "type": "number" }, "feeEstimate": { "description": "Estimated network fee in the input token smallest unit. Omitted when includeFeeEstimate is false or the preview is rate-only.", "type": "string" }, "estimatedFillTimeMs": { "type": "number" }, "protocolFeeBps": { "type": "number" }, "protocolFeeAmount": { "type": "string" }, "priceImpact": { "type": "number" }, "rateOnly": { "type": "boolean" } }, "required": [ "expectedOutput", "minimumOutput", "outputToken", "outputDecimals", "outputSymbol", "routing", "slippageMode", "protocolFeeBps", "protocolFeeAmount" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" }, "requestedSlippageBps": { "minimum": 1, "maximum": 500, "description": "Manual slippage submitted by the client, in basis points", "example": 100, "type": "integer" }, "recommendedSlippageBps": { "minimum": 1, "maximum": 9999, "description": "Minimum slippage recommended by the route provider, in basis points", "example": 500, "type": "integer" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 30 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "451": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "GEO_RESTRICTED" ] }, { "type": "string", "enum": [ "TOKENIZED_ASSET_GEO_RESTRICTED" ] } ] }, "recoveryUrl": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/pool-recover/prepare": { "post": { "operationId": "recoverConversionPrepare", "tags": [ "Transact" ], "description": "Build an unsigned Porto intent and delegation for a pool recover (ragequit). The client calls this after generating the commitment proof, signs the returned intent and delegation, then submits via the standard submit endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "description": "Quote ID from pool-recover quote response", "type": "string" }, "recoverCalldata": { "description": "Canonical encoded Pool.ragequit(proof) calldata (hex)", "pattern": "^0x[0-9a-fA-F]+$", "maxLength": 2048, "type": "string" } }, "required": [ "quoteId", "recoverCalldata" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/accounts/{accountId}/balance": { "get": { "operationId": "getBalances", "tags": [ "Balance & Activity" ], "description": "Retrieve token balances across every supported chain for this account. Each balance contains visible (standard on-chain) available and pending amounts. Returns a totalUsdAmount summarizing all holdings.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "balances": { "description": "One entry per token per chain, each with tiered balance breakdown", "type": "array", "items": { "description": "Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.", "type": "object", "properties": { "chainId": { "example": 8453, "description": "Chain ID where this token resides", "type": "number" }, "chainName": { "example": "Base", "description": "Human-readable chain name", "type": "string" }, "token": { "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Token contract address (EIP-55 checksummed)", "type": "string" }, "tokenSymbol": { "example": "USDC", "description": "Token ticker symbol", "type": "string" }, "decimals": { "example": 6, "description": "Token decimal places", "type": "number" }, "logoUrl": { "example": "https://assets.coingecko.com/coins/images/6319/small/usdc.png", "description": "Token logo URL, or null if unavailable", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visible": { "description": "Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.", "type": "object", "properties": { "available": { "example": "1000000", "description": "Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)", "type": "string" }, "pending": { "example": "500000", "description": "Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pending" ] }, "incognito": { "description": "Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.", "type": "object", "properties": { "pooled": { "description": "Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.", "type": "object", "properties": { "available": { "example": "750000", "description": "Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)", "type": "string" }, "pendingApproval": { "example": "250000", "description": "Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)", "type": "string" }, "pendingWithdrawal": { "example": "500000", "description": "ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)", "type": "string" }, "declined": { "example": "0", "description": "Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pendingApproval", "pendingWithdrawal", "declined" ] } }, "required": [ "pooled" ] }, "usdAmount": { "example": 1.5, "description": "Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "example": 2000.42, "description": "USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceStale": { "example": false, "description": "True when the price is older than the display refresh target but still usable", "type": "boolean" }, "priceObservedAt": { "description": "Oldest source observation used to produce pricePerToken. Null when pricing is unavailable.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "spam": { "example": false, "description": "True if the token is flagged as potential spam or a phishing token", "type": "boolean" } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "visible", "incognito", "usdAmount", "pricePerToken", "priceStale", "priceObservedAt", "spam" ] } }, "totalUsdAmount": { "example": 1.5, "description": "Sum of usdAmount across all balance items. Null when no pricing data is available for any token.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricing": { "type": "object", "properties": { "nonZeroAssetCount": { "description": "Number of non-zero assets that could contribute to totalUsdAmount.", "type": "number" }, "pricedAssetCount": { "description": "Number of non-zero assets with a USD price included in totalUsdAmount.", "type": "number" }, "unpricedAssetCount": { "description": "Number of non-zero assets omitted from totalUsdAmount because price is unavailable.", "type": "number" }, "oldestPriceObservedAt": { "description": "Oldest price observation contributing to totalUsdAmount.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "newestPriceObservedAt": { "description": "Newest price observation contributing to totalUsdAmount.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "nonZeroAssetCount", "pricedAssetCount", "unpricedAssetCount", "oldestPriceObservedAt", "newestPriceObservedAt" ] }, "feeWaiver": { "type": "object", "properties": { "active": { "description": "True when Cloaked service fees are currently waived for this account.", "type": "boolean" }, "source": { "description": "Why fees are waived. activation is the time-limited new-user activation offer; cloakie is the NFT waiver.", "anyOf": [ { "type": "string", "enum": [ "activation" ] }, { "type": "string", "enum": [ "cloakie" ] }, { "type": "null" } ] }, "activeUntil": { "description": "Expiry timestamp for time-limited waivers. Null for non-expiring waivers.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "active", "source", "activeUntil" ] } }, "required": [ "balances", "totalUsdAmount", "pricing", "feeWaiver" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/balance/{chainId}": { "get": { "operationId": "getChainBalances", "tags": [ "Balance & Activity" ], "description": "Retrieve token balances filtered to a single chain. Same response shape as getBalances (visible available/pending) but scoped to the given chainId.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "type": "string" }, "in": "path", "name": "chainId", "required": true, "description": "Chain ID (e.g., 8453 for Base)" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "balances": { "description": "One entry per token per chain, each with tiered balance breakdown", "type": "array", "items": { "description": "Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.", "type": "object", "properties": { "chainId": { "example": 8453, "description": "Chain ID where this token resides", "type": "number" }, "chainName": { "example": "Base", "description": "Human-readable chain name", "type": "string" }, "token": { "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Token contract address (EIP-55 checksummed)", "type": "string" }, "tokenSymbol": { "example": "USDC", "description": "Token ticker symbol", "type": "string" }, "decimals": { "example": 6, "description": "Token decimal places", "type": "number" }, "logoUrl": { "example": "https://assets.coingecko.com/coins/images/6319/small/usdc.png", "description": "Token logo URL, or null if unavailable", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visible": { "description": "Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.", "type": "object", "properties": { "available": { "example": "1000000", "description": "Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)", "type": "string" }, "pending": { "example": "500000", "description": "Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pending" ] }, "incognito": { "description": "Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.", "type": "object", "properties": { "pooled": { "description": "Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.", "type": "object", "properties": { "available": { "example": "750000", "description": "Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)", "type": "string" }, "pendingApproval": { "example": "250000", "description": "Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)", "type": "string" }, "pendingWithdrawal": { "example": "500000", "description": "ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)", "type": "string" }, "declined": { "example": "0", "description": "Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pendingApproval", "pendingWithdrawal", "declined" ] } }, "required": [ "pooled" ] }, "usdAmount": { "example": 1.5, "description": "Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "example": 2000.42, "description": "USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceStale": { "example": false, "description": "True when the price is older than the display refresh target but still usable", "type": "boolean" }, "priceObservedAt": { "description": "Oldest source observation used to produce pricePerToken. Null when pricing is unavailable.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "spam": { "example": false, "description": "True if the token is flagged as potential spam or a phishing token", "type": "boolean" } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "visible", "incognito", "usdAmount", "pricePerToken", "priceStale", "priceObservedAt", "spam" ] } }, "totalUsdAmount": { "example": 1.5, "description": "Sum of usdAmount across all balance items. Null when no pricing data is available for any token.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricing": { "type": "object", "properties": { "nonZeroAssetCount": { "description": "Number of non-zero assets that could contribute to totalUsdAmount.", "type": "number" }, "pricedAssetCount": { "description": "Number of non-zero assets with a USD price included in totalUsdAmount.", "type": "number" }, "unpricedAssetCount": { "description": "Number of non-zero assets omitted from totalUsdAmount because price is unavailable.", "type": "number" }, "oldestPriceObservedAt": { "description": "Oldest price observation contributing to totalUsdAmount.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "newestPriceObservedAt": { "description": "Newest price observation contributing to totalUsdAmount.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "nonZeroAssetCount", "pricedAssetCount", "unpricedAssetCount", "oldestPriceObservedAt", "newestPriceObservedAt" ] }, "feeWaiver": { "type": "object", "properties": { "active": { "description": "True when Cloaked service fees are currently waived for this account.", "type": "boolean" }, "source": { "description": "Why fees are waived. activation is the time-limited new-user activation offer; cloakie is the NFT waiver.", "anyOf": [ { "type": "string", "enum": [ "activation" ] }, { "type": "string", "enum": [ "cloakie" ] }, { "type": "null" } ] }, "activeUntil": { "description": "Expiry timestamp for time-limited waivers. Null for non-expiring waivers.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "active", "source", "activeUntil" ] } }, "required": [ "balances", "totalUsdAmount", "pricing", "feeWaiver" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/balance/{chainId}/{token}": { "get": { "operationId": "getTokenBalance", "tags": [ "Balance & Activity" ], "description": "Retrieve the balance for a single token on a specific chain. Returns visible available and pending amounts. Returns a zero-balance object if the token has never been received and its decimals are known. Returns 503 TOKEN_METADATA_UNAVAILABLE if token decimals cannot be resolved.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "type": "string" }, "in": "path", "name": "chainId", "required": true, "description": "Chain ID" }, { "schema": { "type": "string" }, "in": "path", "name": "token", "required": true, "description": "Token address (0x...)" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.", "content": { "application/json": { "schema": { "description": "Balance for a single token on a single chain. Contains visible available and pending amounts for standard on-chain stealth address holdings.", "type": "object", "properties": { "chainId": { "example": 8453, "description": "Chain ID where this token resides", "type": "number" }, "chainName": { "example": "Base", "description": "Human-readable chain name", "type": "string" }, "token": { "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Token contract address (EIP-55 checksummed)", "type": "string" }, "tokenSymbol": { "example": "USDC", "description": "Token ticker symbol", "type": "string" }, "decimals": { "example": 6, "description": "Token decimal places", "type": "number" }, "logoUrl": { "example": "https://assets.coingecko.com/coins/images/6319/small/usdc.png", "description": "Token logo URL, or null if unavailable", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visible": { "description": "Standard on-chain balances held in stealth addresses. These funds have no privacy pool provenance — they arrived via receives, swaps, or on-ramps.", "type": "object", "properties": { "available": { "example": "1000000", "description": "Balance available to spend immediately — not locked by any pending transaction (stringified bigint, smallest unit)", "type": "string" }, "pending": { "example": "500000", "description": "Balance locked by an outbound transaction that has not yet confirmed on-chain (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pending" ] }, "incognito": { "description": "Incognito balances from privacy pools. The server tracks available, pending withdrawal, pending approval, and declined tiers.", "type": "object", "properties": { "pooled": { "description": "Privacy pool balances. Available is the authoritative withdrawable amount tracked by the server.", "type": "object", "properties": { "available": { "example": "750000", "description": "Sum of ASP-approved, unspent, unlocked commitment values — how much the user can withdraw right now. (stringified bigint, smallest unit)", "type": "string" }, "pendingApproval": { "example": "250000", "description": "Deposits awaiting ASP compliance approval. Will become available automatically once approved. Includes inflight deposits confirmed on-chain but not yet indexed. (stringified bigint, smallest unit)", "type": "string" }, "pendingWithdrawal": { "example": "500000", "description": "ASP-approved pool funds locked by a pending withdrawal. Not available for a new send, but still counted in total balance while the withdrawal confirms. (stringified bigint, smallest unit)", "type": "string" }, "declined": { "example": "0", "description": "Deposits that were not allowed to join the pool by the compliance check. Recoverable back to the visible wallet balance via the recovery flow. Distinct from pendingApproval so clients can prompt the recovery action instead of leaving the user waiting on a state that will never resolve on its own. (stringified bigint, smallest unit)", "type": "string" } }, "required": [ "available", "pendingApproval", "pendingWithdrawal", "declined" ] } }, "required": [ "pooled" ] }, "usdAmount": { "example": 1.5, "description": "Total USD value of visible balance. Null when pricing data is unavailable for a token that has a non-zero balance.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "example": 2000.42, "description": "USD price for one whole token (e.g. 1 ETH). Null when pricing data is unavailable. Use this to compute USD values on the client: amount * pricePerToken.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceStale": { "example": false, "description": "True when the price is older than the display refresh target but still usable", "type": "boolean" }, "priceObservedAt": { "description": "Oldest source observation used to produce pricePerToken. Null when pricing is unavailable.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "spam": { "example": false, "description": "True if the token is flagged as potential spam or a phishing token", "type": "boolean" } }, "required": [ "chainId", "chainName", "token", "tokenSymbol", "decimals", "logoUrl", "visible", "incognito", "usdAmount", "pricePerToken", "priceStale", "priceObservedAt", "spam" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/activities": { "get": { "operationId": "getActivities", "tags": [ "Balance & Activity" ], "description": "List confirmed (on-chain) transactions for the account with cursor-based pagination. The response uses a discriminated union on kind: SEND/RECEIVE/SELF/INCOGNITO_*/NFT_WITHDRAW/DAPP_CALL include a transfers array, SWAP includes a swap object with source and dest token info, BRIDGE and CROSS_CHAIN_SWAP include a bridge object with source, dest, and chain info. For in-flight transactions, use GET /activities/pending.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "quoteId", "required": false, "description": "Return the activity for this quote, within the authenticated account" }, { "schema": { "type": "string" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of activities to return (1-500, default: 100)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Base64-encoded cursor for pagination" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "enum": [ "true", "false" ], "type": "string" } ] }, "in": "query", "name": "hideLikelySpam", "required": false, "description": "When true, likely spam activities are filtered before applying the page limit." }, { "schema": { "anyOf": [ { "type": "boolean" }, { "enum": [ "true", "false" ], "type": "string" } ] }, "in": "query", "name": "hideExternal", "required": false, "description": "When true, external app activity is filtered before applying the page limit." }, { "schema": { "maxItems": 10000, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "in": "query", "name": "addresses", "required": false, "description": "Owned addresses to include. An empty list returns no activities." }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": false, "description": "Owned address to scope the activity feed to." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "txHashes": { "description": "All deduplicated action transaction hashes for this logical operation, in action order.", "type": "array", "items": { "example": "0x...", "type": "string" } }, "executionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "quoteId": { "format": "uuid", "description": "Quote ID that produced this transaction, for correlating pending → confirmed", "type": "string" }, "chainId": { "example": 8453, "type": "number" }, "chainName": { "example": "Base", "type": "string" }, "explorerTxUrlBase": { "description": "Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.", "anyOf": [ { "example": "https://basescan.org/tx/", "type": "string" }, { "type": "null" } ] }, "date": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "SEND" ] }, { "type": "string", "enum": [ "RECEIVE" ] }, { "type": "string", "enum": [ "SELF" ] }, { "type": "string", "enum": [ "SWAP" ] }, { "type": "string", "enum": [ "BRIDGE" ] }, { "type": "string", "enum": [ "CROSS_CHAIN_SWAP" ] }, { "type": "string", "enum": [ "POOL_DEPOSIT" ] }, { "type": "string", "enum": [ "POOL_RECOVER" ] }, { "type": "string", "enum": [ "INCOGNITO_SEND" ] }, { "type": "string", "enum": [ "INCOGNITO_SELF_SEND" ] }, { "type": "string", "enum": [ "NFT_WITHDRAW" ] }, { "type": "string", "enum": [ "DAPP_CALL" ] } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "indexed" ] } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "isExternal": { "description": "True for indexed no-intent transactions signed directly by one of the account's addresses.", "example": false, "type": "boolean" }, "isLikelySpam": { "example": false, "type": "boolean" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the fee, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.001, "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "value", "usdAmount" ] } }, "cloakedFeeBps": { "anyOf": [ { "description": "Cloaked service fee BPS recorded at quote time. 0 when waived.", "type": "number" }, { "type": "null" } ] }, "sourceProvenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "fundingAddresses": { "description": "Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 6, "type": "number" }, "tokenSymbol": { "example": "USDC", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromAddress": { "example": "0x...", "type": "string" }, "toAddress": { "example": "0x...", "type": "string" }, "value": { "example": "1000000", "type": "string" }, "usdAmount": { "description": "USD value of the transfer, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "fromAddress", "toAddress", "value", "usdAmount" ] } }, "swap": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "WETH", "type": "string" }, "destDecimals": { "example": 18, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "500000000000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.5, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the output recipient belongs to the Cloaked account that owns this activity.", "type": "boolean" } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient" ] }, "bridge": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "USDC", "type": "string" }, "destDecimals": { "example": 6, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "1000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.", "type": "boolean" }, "bridgeStatus": { "example": "pending", "type": "string" }, "destChainId": { "example": 8453, "type": "number" }, "destChainName": { "example": "Base", "type": "string" }, "destExplorerTxUrlBase": { "description": "Explorer tx URL prefix for the destination chain; append destTxHash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedFillTimeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundEligibleAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp when an unfilled Across bridge becomes refund-eligible", "type": "string" }, { "type": "null" } ] } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient", "bridgeStatus", "destChainId", "destChainName", "destExplorerTxUrlBase", "estimatedFillTimeMs", "destTxHash", "refundTxHash", "refundEligibleAt" ] }, "pool": { "type": "object", "properties": { "poolAddress": { "example": "0x...", "type": "string" }, "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the pool amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "aspStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "commitmentId": { "type": "string" }, "vettingFee": { "type": "string" }, "vettingFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depositFee": { "type": "string" }, "depositFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "poolAddress", "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "amount", "usdAmount" ] }, "dappMeta": { "type": "object", "properties": { "origin": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "verified": { "description": "Whether the exact app origin is recognized by the server registry. Does not verify the transaction.", "type": "boolean" }, "connectedAddress": { "type": "string" }, "isAccountSetup": { "type": "boolean" } } }, "calldata": { "description": "Raw calls JSON for dapp-call activities: [{ to, value, data }]", "type": "string" } }, "required": [ "txHash", "chainId", "chainName", "explorerTxUrlBase", "date", "kind", "lifecycle", "isExternal", "isLikelySpam", "fees" ] } }, "pagination": { "type": "object", "properties": { "limit": { "example": 100, "type": "number" }, "nextCursor": { "description": "Base64-encoded cursor for next page", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "limit", "nextCursor" ] } }, "required": [ "provenanceLabelGroups", "activity", "pagination" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "post": { "operationId": "queryActivities", "tags": [ "Balance & Activity" ], "description": "List confirmed (on-chain) transactions for the account with cursor-based pagination. The response uses a discriminated union on kind: SEND/RECEIVE/SELF/INCOGNITO_*/NFT_WITHDRAW/DAPP_CALL include a transfers array, SWAP includes a swap object with source and dest token info, BRIDGE and CROSS_CHAIN_SWAP include a bridge object with source, dest, and chain info. For in-flight transactions, use GET /activities/pending.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "format": "uuid", "description": "Return the activity for this quote, within the authenticated account", "type": "string" }, "limit": { "description": "Maximum number of activities to return (1-500, default: 100)", "type": "string" }, "cursor": { "description": "Base64-encoded cursor for pagination", "type": "string" }, "hideLikelySpam": { "description": "When true, likely spam activities are filtered before applying the page limit.", "anyOf": [ { "type": "boolean" }, { "enum": [ "true", "false" ], "type": "string" } ] }, "hideExternal": { "description": "When true, external app activity is filtered before applying the page limit.", "anyOf": [ { "type": "boolean" }, { "enum": [ "true", "false" ], "type": "string" } ] }, "addresses": { "maxItems": 10000, "description": "Owned addresses to include. An empty list returns no activities.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address to scope the activity feed to.", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "txHashes": { "description": "All deduplicated action transaction hashes for this logical operation, in action order.", "type": "array", "items": { "example": "0x...", "type": "string" } }, "executionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "quoteId": { "format": "uuid", "description": "Quote ID that produced this transaction, for correlating pending → confirmed", "type": "string" }, "chainId": { "example": 8453, "type": "number" }, "chainName": { "example": "Base", "type": "string" }, "explorerTxUrlBase": { "description": "Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.", "anyOf": [ { "example": "https://basescan.org/tx/", "type": "string" }, { "type": "null" } ] }, "date": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "SEND" ] }, { "type": "string", "enum": [ "RECEIVE" ] }, { "type": "string", "enum": [ "SELF" ] }, { "type": "string", "enum": [ "SWAP" ] }, { "type": "string", "enum": [ "BRIDGE" ] }, { "type": "string", "enum": [ "CROSS_CHAIN_SWAP" ] }, { "type": "string", "enum": [ "POOL_DEPOSIT" ] }, { "type": "string", "enum": [ "POOL_RECOVER" ] }, { "type": "string", "enum": [ "INCOGNITO_SEND" ] }, { "type": "string", "enum": [ "INCOGNITO_SELF_SEND" ] }, { "type": "string", "enum": [ "NFT_WITHDRAW" ] }, { "type": "string", "enum": [ "DAPP_CALL" ] } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "indexed" ] } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "isExternal": { "description": "True for indexed no-intent transactions signed directly by one of the account's addresses.", "example": false, "type": "boolean" }, "isLikelySpam": { "example": false, "type": "boolean" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the fee, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.001, "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "value", "usdAmount" ] } }, "cloakedFeeBps": { "anyOf": [ { "description": "Cloaked service fee BPS recorded at quote time. 0 when waived.", "type": "number" }, { "type": "null" } ] }, "sourceProvenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "fundingAddresses": { "description": "Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 6, "type": "number" }, "tokenSymbol": { "example": "USDC", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromAddress": { "example": "0x...", "type": "string" }, "toAddress": { "example": "0x...", "type": "string" }, "value": { "example": "1000000", "type": "string" }, "usdAmount": { "description": "USD value of the transfer, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "fromAddress", "toAddress", "value", "usdAmount" ] } }, "swap": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "WETH", "type": "string" }, "destDecimals": { "example": 18, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "500000000000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.5, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the output recipient belongs to the Cloaked account that owns this activity.", "type": "boolean" } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient" ] }, "bridge": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "USDC", "type": "string" }, "destDecimals": { "example": 6, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "1000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.", "type": "boolean" }, "bridgeStatus": { "example": "pending", "type": "string" }, "destChainId": { "example": 8453, "type": "number" }, "destChainName": { "example": "Base", "type": "string" }, "destExplorerTxUrlBase": { "description": "Explorer tx URL prefix for the destination chain; append destTxHash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedFillTimeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundEligibleAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp when an unfilled Across bridge becomes refund-eligible", "type": "string" }, { "type": "null" } ] } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient", "bridgeStatus", "destChainId", "destChainName", "destExplorerTxUrlBase", "estimatedFillTimeMs", "destTxHash", "refundTxHash", "refundEligibleAt" ] }, "pool": { "type": "object", "properties": { "poolAddress": { "example": "0x...", "type": "string" }, "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the pool amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "aspStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "commitmentId": { "type": "string" }, "vettingFee": { "type": "string" }, "vettingFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depositFee": { "type": "string" }, "depositFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "poolAddress", "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "amount", "usdAmount" ] }, "dappMeta": { "type": "object", "properties": { "origin": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "verified": { "description": "Whether the exact app origin is recognized by the server registry. Does not verify the transaction.", "type": "boolean" }, "connectedAddress": { "type": "string" }, "isAccountSetup": { "type": "boolean" } } }, "calldata": { "description": "Raw calls JSON for dapp-call activities: [{ to, value, data }]", "type": "string" } }, "required": [ "txHash", "chainId", "chainName", "explorerTxUrlBase", "date", "kind", "lifecycle", "isExternal", "isLikelySpam", "fees" ] } }, "pagination": { "type": "object", "properties": { "limit": { "example": 100, "type": "number" }, "nextCursor": { "description": "Base64-encoded cursor for next page", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "limit", "nextCursor" ] } }, "required": [ "provenanceLabelGroups", "activity", "pagination" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/activities/search": { "post": { "operationId": "searchActivities", "tags": [ "Balance & Activity" ], "description": "Search confirmed account activity directly involving one Ethereum address.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Ethereum address directly involved in the activity to find.", "type": "string" }, "filters": { "type": "object", "properties": { "hideLikelySpam": { "type": "boolean" }, "hideExternal": { "type": "boolean" } } }, "pagination": { "type": "object", "properties": { "limit": { "minimum": 1, "maximum": 500, "type": "integer" }, "cursor": { "description": "Base64-encoded cursor for pagination", "type": "string" } } }, "include": { "type": "object", "properties": { "summary": { "type": "boolean" } } } }, "required": [ "address" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "searchSummary": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Address directly involved in matching activity.", "type": "string" }, "interactionCount": { "type": "number" }, "chainIds": { "type": "array", "items": { "type": "number" } } }, "required": [ "address", "interactionCount", "chainIds" ] }, "activity": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "txHashes": { "description": "All deduplicated action transaction hashes for this logical operation, in action order.", "type": "array", "items": { "example": "0x...", "type": "string" } }, "executionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "quoteId": { "format": "uuid", "description": "Quote ID that produced this transaction, for correlating pending → confirmed", "type": "string" }, "chainId": { "example": 8453, "type": "number" }, "chainName": { "example": "Base", "type": "string" }, "explorerTxUrlBase": { "description": "Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.", "anyOf": [ { "example": "https://basescan.org/tx/", "type": "string" }, { "type": "null" } ] }, "date": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "SEND" ] }, { "type": "string", "enum": [ "RECEIVE" ] }, { "type": "string", "enum": [ "SELF" ] }, { "type": "string", "enum": [ "SWAP" ] }, { "type": "string", "enum": [ "BRIDGE" ] }, { "type": "string", "enum": [ "CROSS_CHAIN_SWAP" ] }, { "type": "string", "enum": [ "POOL_DEPOSIT" ] }, { "type": "string", "enum": [ "POOL_RECOVER" ] }, { "type": "string", "enum": [ "INCOGNITO_SEND" ] }, { "type": "string", "enum": [ "INCOGNITO_SELF_SEND" ] }, { "type": "string", "enum": [ "NFT_WITHDRAW" ] }, { "type": "string", "enum": [ "DAPP_CALL" ] } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "indexed" ] } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "isExternal": { "description": "True for indexed no-intent transactions signed directly by one of the account's addresses.", "example": false, "type": "boolean" }, "isLikelySpam": { "example": false, "type": "boolean" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the fee, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.001, "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "value", "usdAmount" ] } }, "cloakedFeeBps": { "anyOf": [ { "description": "Cloaked service fee BPS recorded at quote time. 0 when waived.", "type": "number" }, { "type": "null" } ] }, "sourceProvenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "fundingAddresses": { "description": "Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 6, "type": "number" }, "tokenSymbol": { "example": "USDC", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromAddress": { "example": "0x...", "type": "string" }, "toAddress": { "example": "0x...", "type": "string" }, "value": { "example": "1000000", "type": "string" }, "usdAmount": { "description": "USD value of the transfer, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "fromAddress", "toAddress", "value", "usdAmount" ] } }, "swap": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "WETH", "type": "string" }, "destDecimals": { "example": 18, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "500000000000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.5, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the output recipient belongs to the Cloaked account that owns this activity.", "type": "boolean" } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient" ] }, "bridge": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "USDC", "type": "string" }, "destDecimals": { "example": 6, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "1000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.", "type": "boolean" }, "bridgeStatus": { "example": "pending", "type": "string" }, "destChainId": { "example": 8453, "type": "number" }, "destChainName": { "example": "Base", "type": "string" }, "destExplorerTxUrlBase": { "description": "Explorer tx URL prefix for the destination chain; append destTxHash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedFillTimeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundEligibleAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp when an unfilled Across bridge becomes refund-eligible", "type": "string" }, { "type": "null" } ] } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient", "bridgeStatus", "destChainId", "destChainName", "destExplorerTxUrlBase", "estimatedFillTimeMs", "destTxHash", "refundTxHash", "refundEligibleAt" ] }, "pool": { "type": "object", "properties": { "poolAddress": { "example": "0x...", "type": "string" }, "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the pool amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "aspStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "commitmentId": { "type": "string" }, "vettingFee": { "type": "string" }, "vettingFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depositFee": { "type": "string" }, "depositFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "poolAddress", "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "amount", "usdAmount" ] }, "dappMeta": { "type": "object", "properties": { "origin": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "verified": { "description": "Whether the exact app origin is recognized by the server registry. Does not verify the transaction.", "type": "boolean" }, "connectedAddress": { "type": "string" }, "isAccountSetup": { "type": "boolean" } } }, "calldata": { "description": "Raw calls JSON for dapp-call activities: [{ to, value, data }]", "type": "string" } }, "required": [ "txHash", "chainId", "chainName", "explorerTxUrlBase", "date", "kind", "lifecycle", "isExternal", "isLikelySpam", "fees" ] } }, "pagination": { "type": "object", "properties": { "limit": { "example": 100, "type": "number" }, "nextCursor": { "description": "Base64-encoded cursor for the next confirmed activity page", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "limit", "nextCursor" ] } }, "required": [ "provenanceLabelGroups", "activity", "pagination" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/activities/pending/status": { "post": { "operationId": "getPendingActivityStatuses", "tags": [ "Balance & Activity" ], "description": "Return the current lifecycle projection for known pending activity quote IDs. Missing or no-longer-pending IDs are omitted.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteIds": { "minItems": 1, "maxItems": 100, "uniqueItems": true, "type": "array", "items": { "format": "uuid", "type": "string" } } }, "required": [ "quoteIds" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "object", "properties": { "quoteId": { "format": "uuid", "type": "string" }, "txHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "bridge": { "type": "object", "properties": { "bridgeStatus": { "example": "pending", "type": "string" }, "destTxHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bridgeStatus", "destTxHash", "refundTxHash" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "quoteId", "txHash", "lifecycle", "updatedAt" ] } } }, "required": [ "statuses" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/activities/pending": { "get": { "operationId": "getPendingActivities", "tags": [ "Balance & Activity" ], "description": "List in-flight relay transactions (queued, pending, stuck) and recently confirmed/failed transactions for the account. The response uses the same shape as GET /activities: same kind values, same payload sub-objects. The lifecycle.state discriminates between 'in_flight', 'indexed', and 'failed'. Recently confirmed transactions are included for up to 5 minutes so the client can show continuous state while the transaction is indexed.", "parameters": [ { "schema": { "maxItems": 10000, "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "in": "query", "name": "addresses", "required": false, "description": "Owned addresses to include. An empty list returns no activities." }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": false, "description": "Owned address to scope pending activity to." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "pending": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "txHashes": { "description": "All deduplicated action transaction hashes for this logical operation, in action order.", "type": "array", "items": { "example": "0x...", "type": "string" } }, "executionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "quoteId": { "format": "uuid", "description": "Quote ID that produced this transaction, for correlating pending → confirmed", "type": "string" }, "chainId": { "example": 8453, "type": "number" }, "chainName": { "example": "Base", "type": "string" }, "explorerTxUrlBase": { "description": "Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.", "anyOf": [ { "example": "https://basescan.org/tx/", "type": "string" }, { "type": "null" } ] }, "date": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "SEND" ] }, { "type": "string", "enum": [ "RECEIVE" ] }, { "type": "string", "enum": [ "SELF" ] }, { "type": "string", "enum": [ "SWAP" ] }, { "type": "string", "enum": [ "BRIDGE" ] }, { "type": "string", "enum": [ "CROSS_CHAIN_SWAP" ] }, { "type": "string", "enum": [ "POOL_DEPOSIT" ] }, { "type": "string", "enum": [ "POOL_RECOVER" ] }, { "type": "string", "enum": [ "INCOGNITO_SEND" ] }, { "type": "string", "enum": [ "INCOGNITO_SELF_SEND" ] }, { "type": "string", "enum": [ "NFT_WITHDRAW" ] }, { "type": "string", "enum": [ "DAPP_CALL" ] } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "indexed" ] } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "isExternal": { "description": "True for indexed no-intent transactions signed directly by one of the account's addresses.", "example": false, "type": "boolean" }, "isLikelySpam": { "example": false, "type": "boolean" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the fee, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.001, "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "value", "usdAmount" ] } }, "cloakedFeeBps": { "anyOf": [ { "description": "Cloaked service fee BPS recorded at quote time. 0 when waived.", "type": "number" }, { "type": "null" } ] }, "sourceProvenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "fundingAddresses": { "description": "Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 6, "type": "number" }, "tokenSymbol": { "example": "USDC", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromAddress": { "example": "0x...", "type": "string" }, "toAddress": { "example": "0x...", "type": "string" }, "value": { "example": "1000000", "type": "string" }, "usdAmount": { "description": "USD value of the transfer, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "fromAddress", "toAddress", "value", "usdAmount" ] } }, "swap": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "WETH", "type": "string" }, "destDecimals": { "example": 18, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "500000000000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.5, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the output recipient belongs to the Cloaked account that owns this activity.", "type": "boolean" } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient" ] }, "bridge": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "USDC", "type": "string" }, "destDecimals": { "example": 6, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "1000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.", "type": "boolean" }, "bridgeStatus": { "example": "pending", "type": "string" }, "destChainId": { "example": 8453, "type": "number" }, "destChainName": { "example": "Base", "type": "string" }, "destExplorerTxUrlBase": { "description": "Explorer tx URL prefix for the destination chain; append destTxHash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedFillTimeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundEligibleAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp when an unfilled Across bridge becomes refund-eligible", "type": "string" }, { "type": "null" } ] } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient", "bridgeStatus", "destChainId", "destChainName", "destExplorerTxUrlBase", "estimatedFillTimeMs", "destTxHash", "refundTxHash", "refundEligibleAt" ] }, "pool": { "type": "object", "properties": { "poolAddress": { "example": "0x...", "type": "string" }, "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the pool amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "aspStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "commitmentId": { "type": "string" }, "vettingFee": { "type": "string" }, "vettingFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depositFee": { "type": "string" }, "depositFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "poolAddress", "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "amount", "usdAmount" ] }, "dappMeta": { "type": "object", "properties": { "origin": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "verified": { "description": "Whether the exact app origin is recognized by the server registry. Does not verify the transaction.", "type": "boolean" }, "connectedAddress": { "type": "string" }, "isAccountSetup": { "type": "boolean" } } }, "calldata": { "description": "Raw calls JSON for dapp-call activities: [{ to, value, data }]", "type": "string" } }, "required": [ "txHash", "chainId", "chainName", "explorerTxUrlBase", "date", "kind", "lifecycle", "isExternal", "isLikelySpam", "fees" ] } } }, "required": [ "provenanceLabelGroups", "pending" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "post": { "operationId": "queryPendingActivities", "tags": [ "Balance & Activity" ], "description": "List in-flight relay transactions (queued, pending, stuck) and recently confirmed/failed transactions for the account. The response uses the same shape as GET /activities: same kind values, same payload sub-objects. The lifecycle.state discriminates between 'in_flight', 'indexed', and 'failed'. Recently confirmed transactions are included for up to 5 minutes so the client can show continuous state while the transaction is indexed.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "maxItems": 10000, "description": "Owned addresses to include. An empty list returns no activities.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address to scope pending activity to.", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provenanceLabelGroups": { "type": "object", "additionalProperties": { "type": "object", "properties": { "encryptedTagSources": { "description": "Only receive sources with encrypted user tag payloads needed for client-side label display.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "systemLabels": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "enum": [ "dapp_used" ] }, { "type": "string", "enum": [ "contact_receive" ] }, { "type": "string", "enum": [ "referral_reward" ] } ] }, "text": { "description": "Short server-derived label text for display", "type": "string" }, "apps": { "description": "App identities revealed when a dapp label is opened", "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "displayName", "iconUrl" ] } }, "iconUrl": { "anyOf": [ { "description": "Optional safe proxied icon URL for system labels with app metadata", "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "text" ] } }, "hasNoTag": { "description": "True when represented provenance includes at least one untagged source.", "type": "boolean" }, "hasOlderFunds": { "description": "True when represented provenance includes older/pre-tagging funds.", "type": "boolean" }, "hasUnknown": { "description": "True when represented provenance includes unresolved provenance.", "type": "boolean" } }, "required": [ "encryptedTagSources", "systemLabels", "hasNoTag", "hasOlderFunds", "hasUnknown" ] } }, "pending": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "txHashes": { "description": "All deduplicated action transaction hashes for this logical operation, in action order.", "type": "array", "items": { "example": "0x...", "type": "string" } }, "executionStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "manual_review" ] } ] }, "quoteId": { "format": "uuid", "description": "Quote ID that produced this transaction, for correlating pending → confirmed", "type": "string" }, "chainId": { "example": 8453, "type": "number" }, "chainName": { "example": "Base", "type": "string" }, "explorerTxUrlBase": { "description": "Explorer tx URL prefix for the activity's chain; append a tx hash to build a link.", "anyOf": [ { "example": "https://basescan.org/tx/", "type": "string" }, { "type": "null" } ] }, "date": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "SEND" ] }, { "type": "string", "enum": [ "RECEIVE" ] }, { "type": "string", "enum": [ "SELF" ] }, { "type": "string", "enum": [ "SWAP" ] }, { "type": "string", "enum": [ "BRIDGE" ] }, { "type": "string", "enum": [ "CROSS_CHAIN_SWAP" ] }, { "type": "string", "enum": [ "POOL_DEPOSIT" ] }, { "type": "string", "enum": [ "POOL_RECOVER" ] }, { "type": "string", "enum": [ "INCOGNITO_SEND" ] }, { "type": "string", "enum": [ "INCOGNITO_SELF_SEND" ] }, { "type": "string", "enum": [ "NFT_WITHDRAW" ] }, { "type": "string", "enum": [ "DAPP_CALL" ] } ] }, "lifecycle": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "indexed" ] } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "in_flight" ] }, "relayStatus": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "stuck" ] }, { "type": "string", "enum": [ "confirmed" ] } ] } }, "required": [ "state", "relayStatus" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureStage": { "anyOf": [ { "type": "string", "enum": [ "pre_broadcast" ] }, { "type": "string", "enum": [ "on_chain" ] }, { "type": "string", "enum": [ "unknown" ] } ] } }, "required": [ "state", "reason" ] } ] }, "isExternal": { "description": "True for indexed no-intent transactions signed directly by one of the account's addresses.", "example": false, "type": "boolean" }, "isLikelySpam": { "example": false, "type": "boolean" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the fee, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.001, "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "value", "usdAmount" ] } }, "cloakedFeeBps": { "anyOf": [ { "description": "Cloaked service fee BPS recorded at quote time. 0 when waived.", "type": "number" }, { "type": "null" } ] }, "sourceProvenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] }, "fundingAddresses": { "description": "Owned Cloaked addresses that funded this outbound activity. Omitted when the activity has no visible address funding source.", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 6, "type": "number" }, "tokenSymbol": { "example": "USDC", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromAddress": { "example": "0x...", "type": "string" }, "toAddress": { "example": "0x...", "type": "string" }, "value": { "example": "1000000", "type": "string" }, "usdAmount": { "description": "USD value of the transfer, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "resolved" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "outputSystemTags": { "description": "System tags that describe only the exact current output and never propagate to successor outputs.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "sourceLabelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "description": "Number of pre-launch checkpoint provenance markers represented by this balance.", "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "displayContext": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "enum": [ "fresh_receive" ] }, { "type": "string", "enum": [ "cloaked_action_output" ] }, { "type": "string", "enum": [ "mixed_current_outputs" ] }, { "type": "string", "enum": [ "carried_source" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "currentOutputCount": { "minimum": 0, "type": "integer" }, "sourceCount": { "minimum": 0, "type": "integer" }, "actionTypes": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "currentOutputCount", "sourceCount", "actionTypes" ] }, "funding": { "type": "object", "properties": { "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "labelGroupId", "olderFundsCount", "unresolvedReasons" ] }, "association": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "labelGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unresolvedReasons": { "type": "array", "items": { "type": "string" } }, "ignoredUnsolicitedCount": { "minimum": 0, "type": "integer" }, "summary": { "type": "object", "properties": { "sourceCount": { "minimum": 0, "type": "integer" }, "userTaggedSourceCount": { "minimum": 0, "type": "integer" }, "untaggedSourceCount": { "minimum": 0, "type": "integer" }, "olderFundsCount": { "minimum": 0, "type": "integer" }, "unknownCount": { "minimum": 0, "type": "integer" } }, "required": [ "sourceCount", "userTaggedSourceCount", "untaggedSourceCount", "olderFundsCount", "unknownCount" ] } }, "required": [ "status", "labelGroupId", "olderFundsCount", "unresolvedReasons", "ignoredUnsolicitedCount", "summary" ] }, "display": { "type": "object", "properties": { "badgeKind": { "anyOf": [ { "type": "string", "enum": [ "tagged" ] }, { "type": "string", "enum": [ "mixed" ] }, { "type": "string", "enum": [ "older_funds" ] }, { "type": "string", "enum": [ "unknown" ] }, { "type": "string", "enum": [ "untagged" ] } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fundingLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "associationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "badgeKind", "label", "fundingLabel", "associationLabel" ] }, "editableSource": { "description": "The single directly editable receive source for this item, when one exists.", "anyOf": [ { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] }, { "type": "null" } ] } }, "required": [ "status", "outputSystemTags", "sourceLabelGroupId", "olderFundsCount", "unresolvedReasons", "displayContext", "funding", "association", "display", "editableSource" ] } }, "required": [ "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "fromAddress", "toAddress", "value", "usdAmount" ] } }, "swap": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "WETH", "type": "string" }, "destDecimals": { "example": 18, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "500000000000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 0.5, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the output recipient belongs to the Cloaked account that owns this activity.", "type": "boolean" } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient" ] }, "bridge": { "type": "object", "properties": { "sourceTokenAddress": { "example": "0x...", "type": "string" }, "sourceDecimals": { "example": 6, "type": "number" }, "sourceTokenSymbol": { "example": "USDC", "type": "string" }, "sourceLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "example": "1000000", "type": "string" }, "sourceUsdAmount": { "description": "USD value of the source amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "destTokenAddress": { "example": "0x...", "type": "string" }, "destTokenSymbol": { "example": "USDC", "type": "string" }, "destDecimals": { "example": 6, "type": "number" }, "destLogoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destAmount": { "example": "1000000", "type": "string" }, "destUsdAmount": { "description": "USD value of the destination amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "outputRecipient": { "example": "0x...", "type": "string" }, "outputRecipientIsOwnAddress": { "description": "Whether the final output recipient belongs to this Cloaked account. Omitted for legacy records.", "type": "boolean" }, "bridgeStatus": { "example": "pending", "type": "string" }, "destChainId": { "example": 8453, "type": "number" }, "destChainName": { "example": "Base", "type": "string" }, "destExplorerTxUrlBase": { "description": "Explorer tx URL prefix for the destination chain; append destTxHash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedFillTimeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundTxHash": { "anyOf": [ { "example": "0x...", "type": "string" }, { "type": "null" } ] }, "refundEligibleAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp when an unfilled Across bridge becomes refund-eligible", "type": "string" }, { "type": "null" } ] } }, "required": [ "sourceTokenAddress", "sourceDecimals", "sourceTokenSymbol", "sourceLogoUrl", "sourceAmount", "sourceUsdAmount", "destTokenAddress", "destTokenSymbol", "destDecimals", "destLogoUrl", "destAmount", "destUsdAmount", "outputRecipient", "bridgeStatus", "destChainId", "destChainName", "destExplorerTxUrlBase", "estimatedFillTimeMs", "destTxHash", "refundTxHash", "refundEligibleAt" ] }, "pool": { "type": "object", "properties": { "poolAddress": { "example": "0x...", "type": "string" }, "tokenAddress": { "example": "0x...", "type": "string" }, "decimals": { "example": 18, "type": "number" }, "tokenSymbol": { "example": "ETH", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "example": "1000000000000000", "type": "string" }, "usdAmount": { "description": "USD value of the pool amount, or null when token USD pricing is unavailable.", "anyOf": [ { "example": 1, "type": "number" }, { "type": "null" } ] }, "aspStatus": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "commitmentId": { "type": "string" }, "vettingFee": { "type": "string" }, "vettingFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depositFee": { "type": "string" }, "depositFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "poolAddress", "tokenAddress", "decimals", "tokenSymbol", "logoUrl", "amount", "usdAmount" ] }, "dappMeta": { "type": "object", "properties": { "origin": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "verified": { "description": "Whether the exact app origin is recognized by the server registry. Does not verify the transaction.", "type": "boolean" }, "connectedAddress": { "type": "string" }, "isAccountSetup": { "type": "boolean" } } }, "calldata": { "description": "Raw calls JSON for dapp-call activities: [{ to, value, data }]", "type": "string" } }, "required": [ "txHash", "chainId", "chainName", "explorerTxUrlBase", "date", "kind", "lifecycle", "isExternal", "isLikelySpam", "fees" ] } } }, "required": [ "provenanceLabelGroups", "pending" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/activity-notes": { "get": { "operationId": "listActivityNotes", "tags": [ "Balance & Activity" ], "description": "List client-encrypted private notes attached to account activity.", "parameters": [ { "schema": { "minimum": 1, "maximum": 500, "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "reference": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "intent" ] }, "quoteId": { "format": "uuid", "type": "string" } }, "required": [ "type", "quoteId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "chainId": { "minimum": 1, "type": "integer" }, "txHash": { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" } }, "required": [ "type", "chainId", "txHash" ] } ] }, "notePayloadCiphertext": { "maxLength": 8192, "pattern": "^cloaked-aead:v1:activity-note\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Client-encrypted private activity note payload.", "type": "string" }, "notePayloadUpdatedAt": { "format": "date-time", "type": "string" } }, "required": [ "reference", "notePayloadCiphertext", "notePayloadUpdatedAt" ] } }, "pagination": { "type": "object", "properties": { "limit": { "minimum": 1, "maximum": 500, "type": "integer" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "limit", "nextCursor" ] } }, "required": [ "notes", "pagination" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "put": { "operationId": "setActivityNote", "tags": [ "Balance & Activity" ], "description": "Set or clear a client-encrypted private note on one account activity.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "intent" ] }, "quoteId": { "format": "uuid", "type": "string" } }, "required": [ "type", "quoteId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "chainId": { "minimum": 1, "type": "integer" }, "txHash": { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" } }, "required": [ "type", "chainId", "txHash" ] } ] }, "notePayloadCiphertext": { "anyOf": [ { "maxLength": 8192, "pattern": "^cloaked-aead:v1:activity-note\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Client-encrypted private activity note payload.", "type": "string" }, { "type": "null" } ] } }, "required": [ "reference", "notePayloadCiphertext" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "anyOf": [ { "type": "object", "properties": { "reference": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "intent" ] }, "quoteId": { "format": "uuid", "type": "string" } }, "required": [ "type", "quoteId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "chainId": { "minimum": 1, "type": "integer" }, "txHash": { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" } }, "required": [ "type", "chainId", "txHash" ] } ] }, "notePayloadCiphertext": { "maxLength": 8192, "pattern": "^cloaked-aead:v1:activity-note\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Client-encrypted private activity note payload.", "type": "string" }, "notePayloadUpdatedAt": { "format": "date-time", "type": "string" } }, "required": [ "reference", "notePayloadCiphertext", "notePayloadUpdatedAt" ] }, { "type": "null" } ] } }, "required": [ "note" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/deposit-review/summary": { "get": { "operationId": "getDepositReviewSummary", "tags": [ "Balance & Activity" ], "description": "Return deposit review counts and address markers for the account.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "needsReviewCount": { "minimum": 0, "type": "integer" }, "unseenNeedsReview": { "minimum": 0, "type": "integer" }, "markers": { "type": "array", "items": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" } }, "required": [ "address" ] } } }, "required": [ "needsReviewCount", "unseenNeedsReview", "markers" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/deposit-review": { "get": { "operationId": "getDepositReview", "tags": [ "Balance & Activity" ], "description": "Return one review row per fresh inbound address, including current review state, visible assets, tags, and Incognito deposit progress.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "snapshotId", "required": false, "description": "Account-scoped display snapshot, reusable for 30 seconds. Omit from requests to refresh; missing or expired snapshots rebuild." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "needs_review" ] }, { "type": "string", "enum": [ "in_progress" ] }, { "type": "string", "enum": [ "done" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "in": "query", "name": "tab", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshotId": { "format": "uuid", "description": "Account-scoped display snapshot, reusable for 30 seconds. Omit from requests to refresh; missing or expired snapshots rebuild.", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "reviewStatus": { "anyOf": [ { "type": "string", "enum": [ "needs_review" ] }, { "type": "string", "enum": [ "in_progress" ] }, { "type": "string", "enum": [ "done" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "statusReason": { "anyOf": [ { "type": "string", "enum": [ "untagged" ] }, { "type": "string", "enum": [ "tags_added" ] }, { "type": "string", "enum": [ "pool_deposit_in_progress" ] }, { "type": "string", "enum": [ "pool_deposit_rejected" ] }, { "type": "string", "enum": [ "pool_deposited" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "provenanceSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable provenance source key", "type": "string" }, "kind": { "type": "string", "enum": [ "receive" ] }, "origin": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" } }, "required": [ "chainId", "txHash", "transferOrLogIndex" ] }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Owned address where this receive source originally landed", "type": "string" }, "tagPayloadCiphertext": { "anyOf": [ { "maxLength": 4096, "pattern": "^cloaked-aead:v1:provenance-tag\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$", "description": "Optional client-encrypted provenance tag payload ciphertext", "type": "string" }, { "type": "null" } ] }, "tagPayloadUpdatedAt": { "anyOf": [ { "format": "date-time", "description": "ISO timestamp for the last provenance tag payload update", "type": "string" }, { "type": "null" } ] }, "tagEligibility": { "anyOf": [ { "type": "string", "enum": [ "eligible" ] }, { "type": "string", "enum": [ "received_before_tagging" ] } ] }, "tagEditable": { "description": "True when this source is a traceable external receive that may be tagged by the current account", "type": "boolean" }, "systemTags": { "description": "Server-derived tags that follow this funding lineage", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dapp-used" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "dapp_used" ] }, "evidence": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "origin", "displayName", "iconUrl", "lastUsedAt" ] } }, "matchedOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "address", "origins", "matchedOrigin", "latestUsedAt" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact-receive" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "contact_receive" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "contactName": { "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "contactAddress", "contactName" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "referral-reward" ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "referral_reward" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "recipientAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "recipientAddress", "tokenAddress", "amount" ] } }, "required": [ "type", "text", "explanationKey", "evidence" ] } ] } } }, "required": [ "id", "kind", "origin", "address", "tagPayloadCiphertext", "tagPayloadUpdatedAt", "tagEligibility", "tagEditable", "systemTags" ] } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "outputSystemTags": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "id": { "type": "string" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "reviewStatus": { "anyOf": [ { "type": "string", "enum": [ "needs_review" ] }, { "type": "string", "enum": [ "in_progress" ] }, { "type": "string", "enum": [ "done" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "statusReason": { "anyOf": [ { "type": "string", "enum": [ "untagged" ] }, { "type": "string", "enum": [ "tags_added" ] }, { "type": "string", "enum": [ "pool_deposit_in_progress" ] }, { "type": "string", "enum": [ "pool_deposit_rejected" ] }, { "type": "string", "enum": [ "pool_deposited" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "chainId": { "type": "integer" }, "chainName": { "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "minimum": 0, "type": "integer" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Displayed amount in smallest unit", "type": "string" }, "available": { "description": "Currently available visible amount in smallest unit", "type": "string" }, "pending": { "description": "Currently pending visible amount in smallest unit", "type": "string" }, "receiveCount": { "minimum": 0, "type": "integer" }, "rawReceiveCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "lastReceivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "receiveTxHash": { "anyOf": [ { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, { "type": "null" } ] }, "usdAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "poolMinDeposit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canConvert": { "type": "boolean" }, "convertUnavailableReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "poolDeposit": { "anyOf": [ { "type": "object", "properties": { "commitmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "confirmed" ] }, { "type": "string", "enum": [ "asp_pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "txHash": { "anyOf": [ { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Pool deposit amount in smallest unit", "type": "string" }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "commitmentId", "status", "txHash", "amount", "updatedAt" ] }, { "type": "null" } ] } }, "required": [ "id", "address", "reviewStatus", "statusReason", "chainId", "chainName", "tokenAddress", "tokenSymbol", "decimals", "logoUrl", "amount", "available", "pending", "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "lastReceivedAt", "receiveTxHash", "usdAmount", "pricePerToken", "poolMinDeposit", "canConvert", "convertUnavailableReason", "poolDeposit" ] } }, "primaryAsset": { "type": "object", "properties": { "outputSystemTags": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "privacy-provider-origin" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "privacy-pools" ] }, { "type": "string", "enum": [ "privacy-boost" ] } ] }, "text": { "description": "Short server-derived tag text for display", "type": "string" }, "explanationKey": { "type": "string", "enum": [ "privacy_provider_origin" ] }, "evidence": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "transferOrLogIndex": { "minimum": 0, "type": "integer" }, "receiveFromAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "entrypointAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "poolTransferOrLogIndex": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "chainId", "txHash", "transferOrLogIndex", "receiveFromAddress", "poolAddress", "entrypointAddress", "poolTransferOrLogIndex" ] } }, "required": [ "type", "provider", "text", "explanationKey", "evidence" ] } }, "id": { "type": "string" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "reviewStatus": { "anyOf": [ { "type": "string", "enum": [ "needs_review" ] }, { "type": "string", "enum": [ "in_progress" ] }, { "type": "string", "enum": [ "done" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "statusReason": { "anyOf": [ { "type": "string", "enum": [ "untagged" ] }, { "type": "string", "enum": [ "tags_added" ] }, { "type": "string", "enum": [ "pool_deposit_in_progress" ] }, { "type": "string", "enum": [ "pool_deposit_rejected" ] }, { "type": "string", "enum": [ "pool_deposited" ] }, { "type": "string", "enum": [ "skipped" ] } ] }, "chainId": { "type": "integer" }, "chainName": { "type": "string" }, "tokenAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "tokenSymbol": { "type": "string" }, "decimals": { "minimum": 0, "type": "integer" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Displayed amount in smallest unit", "type": "string" }, "available": { "description": "Currently available visible amount in smallest unit", "type": "string" }, "pending": { "description": "Currently pending visible amount in smallest unit", "type": "string" }, "receiveCount": { "minimum": 0, "type": "integer" }, "rawReceiveCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "lastReceivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "receiveTxHash": { "anyOf": [ { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, { "type": "null" } ] }, "usdAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pricePerToken": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "poolMinDeposit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canConvert": { "type": "boolean" }, "convertUnavailableReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "poolDeposit": { "anyOf": [ { "type": "object", "properties": { "commitmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "confirmed" ] }, { "type": "string", "enum": [ "asp_pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "txHash": { "anyOf": [ { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Pool deposit amount in smallest unit", "type": "string" }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "commitmentId", "status", "txHash", "amount", "updatedAt" ] }, { "type": "null" } ] } }, "required": [ "id", "address", "reviewStatus", "statusReason", "chainId", "chainName", "tokenAddress", "tokenSymbol", "decimals", "logoUrl", "amount", "available", "pending", "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "lastReceivedAt", "receiveTxHash", "usdAmount", "pricePerToken", "poolMinDeposit", "canConvert", "convertUnavailableReason", "poolDeposit" ] }, "receiveCount": { "minimum": 0, "type": "integer" }, "rawReceiveCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionCount": { "minimum": 0, "type": "integer" }, "trustedReceiveActionTypes": { "type": "array", "items": { "type": "string" } }, "assetCount": { "minimum": 0, "type": "integer" }, "chainCount": { "minimum": 0, "type": "integer" }, "lastReceivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "usdAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "canConvert": { "type": "boolean" } }, "required": [ "id", "address", "reviewStatus", "statusReason", "provenanceSources", "assets", "primaryAsset", "receiveCount", "rawReceiveCount", "trustedReceiveActionCount", "trustedReceiveActionTypes", "assetCount", "chainCount", "lastReceivedAt", "usdAmount", "canConvert" ] } }, "counts": { "type": "object", "properties": { "needsReview": { "minimum": 0, "type": "integer" }, "inProgress": { "minimum": 0, "type": "integer" }, "done": { "minimum": 0, "type": "integer" }, "skipped": { "minimum": 0, "type": "integer" } }, "required": [ "needsReview", "inProgress", "done", "skipped" ] }, "pageInfo": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" }, "limit": { "minimum": 1, "type": "integer" } }, "required": [ "nextCursor", "hasMore", "limit" ] }, "unseenNeedsReview": { "minimum": 0, "description": "needs-review addresses received after the account last opened Review. Drives the notification badge; 0 once everything current has been seen.", "type": "integer" } }, "required": [ "items", "counts", "pageInfo", "unseenNeedsReview" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/deposit-review/seen": { "post": { "operationId": "markDepositReviewSeen", "tags": [ "Balance & Activity" ], "description": "Mark the account's deposit-review notifications as seen, clearing the Review badge. Idempotent; the marker only moves forward.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "seenAt": { "format": "date-time", "description": "The persisted \"seen\" marker after this request.", "type": "string" } }, "required": [ "seenAt" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/deposit-review/skipped/{address}": { "put": { "operationId": "skipDepositReviewAddress", "tags": [ "Balance & Activity" ], "description": "Move an address-level deposit review item to Skipped through the supplied receive snapshot.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lastReceivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rawReceiveCount": { "minimum": 0, "maximum": 2147483647, "type": "integer" } }, "required": [ "lastReceivedAt", "rawReceiveCount" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "skip": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "lastReceivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rawReceiveCount": { "minimum": 0, "type": "integer" }, "skippedAt": { "format": "date-time", "type": "string" } }, "required": [ "address", "lastReceivedAt", "rawReceiveCount", "skippedAt" ] } }, "required": [ "skip" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "delete": { "operationId": "restoreDepositReviewAddress", "tags": [ "Balance & Activity" ], "description": "Return a skipped address-level deposit review item to Needs Your Review.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "boolean", "enum": [ true ] } }, "required": [ "restored" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/contact-email": { "get": { "operationId": "getContactEmail", "tags": [ "Account" ], "description": "Return the account's optional contact email, or null if none is set.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "anyOf": [ { "minLength": 3, "maxLength": 320, "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "description": "Optional contact email for the account.", "type": "string" }, { "type": "null" } ] } }, "required": [ "email" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "put": { "operationId": "setContactEmail", "tags": [ "Account" ], "description": "Set or replace the account's optional contact email. Used for account updates, product news, and support/feedback outreach.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "minLength": 3, "maxLength": 320, "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "description": "Optional contact email for the account.", "type": "string" } }, "required": [ "email" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "anyOf": [ { "minLength": 3, "maxLength": 320, "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "description": "Optional contact email for the account.", "type": "string" }, { "type": "null" } ] } }, "required": [ "email" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "delete": { "operationId": "deleteContactEmail", "tags": [ "Account" ], "description": "Remove the account's contact email. Idempotent.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "anyOf": [ { "minLength": 3, "maxLength": 320, "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "description": "Optional contact email for the account.", "type": "string" }, { "type": "null" } ] } }, "required": [ "email" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/profile-prompts/{promptId}/dismissal": { "put": { "operationId": "dismissProfilePrompt", "tags": [ "Account" ], "description": "Permanently dismiss an allowed profile prompt for this account across browsers and devices. Idempotent.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "enum": [ "backup-reminder", "custom-ens", "referrals" ], "type": "string" }, "in": "path", "name": "promptId", "required": true, "description": "A profile prompt that supports permanent dismissal." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "promptId": { "enum": [ "backup-reminder", "custom-ens", "referrals" ], "type": "string" }, "dismissedAt": { "format": "date-time", "type": "string" } }, "required": [ "promptId", "dismissedAt" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/address-book": { "get": { "operationId": "getAddressBook", "tags": [ "Account" ], "description": "List the account's saved contacts, most recently used first.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EIP-55 checksummed contact address.", "type": "string" }, "name": { "minLength": 1, "maxLength": 64, "description": "Display name for the saved contact.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "address", "name", "lastUsedAt", "createdAt", "updatedAt" ] } } }, "required": [ "entries" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/address-book/ownership/{address}": { "get": { "operationId": "getAddressBookAddressOwnership", "tags": [ "Account" ], "description": "Check whether an address belongs to the current Cloaked account.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "isOwnAddress": { "type": "boolean" } }, "required": [ "isOwnAddress" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/address-book/{address}": { "put": { "operationId": "upsertAddressBookEntry", "tags": [ "Account" ], "description": "Save or rename a contact. The address is normalized to EIP-55 checksummed form. Requires a member spend-key signature over the canonical save-contact message.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 64, "description": "Display name for the saved contact.", "type": "string" }, "signature": { "pattern": "^0x[0-9a-fA-F]{130}$", "description": "Member spend-key signature over the canonical save-contact message (personal_sign).", "type": "string" }, "issuedAt": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "description": "ISO-8601 timestamp embedded in the signed message. Signatures expire 10 minutes after issuedAt; timestamps up to 60 seconds ahead of server time are accepted for clock skew.", "type": "string" } }, "required": [ "name", "signature", "issuedAt" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EIP-55 checksummed contact address.", "type": "string" }, "name": { "minLength": 1, "maxLength": 64, "description": "Display name for the saved contact.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "address", "name", "lastUsedAt", "createdAt", "updatedAt" ] } }, "required": [ "entry" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "delete": { "operationId": "deleteAddressBookEntry", "tags": [ "Account" ], "description": "Remove a saved contact. Idempotent.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "path", "name": "address", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/referrals/attribution": { "get": { "operationId": "getAccountReferralAttribution", "tags": [ "Account Management" ], "description": "Return this account's referral relationship, including its snapshotted terms and current status.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "referrerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerShareBps": { "minimum": 1, "maximum": 10000, "type": "integer" }, "referredDiscountBps": { "minimum": 0, "maximum": 10000, "type": "integer" }, "minimumRewardUsdCents": { "minimum": 0, "type": "integer" }, "earningStartsAt": { "format": "date-time", "type": "string" }, "earningEndsAt": { "format": "date-time", "type": "string" }, "revokedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "ended" ] }, { "type": "string", "enum": [ "expired" ] } ] } }, "required": [ "referrerName", "referrerShareBps", "referredDiscountBps", "minimumRewardUsdCents", "earningStartsAt", "earningEndsAt", "revokedAt", "status" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "delete": { "operationId": "endAccountReferralAttribution", "tags": [ "Account Management" ], "description": "Permanently end this account's future referral discount and its referrer's future fee share.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "referrerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerShareBps": { "minimum": 1, "maximum": 10000, "type": "integer" }, "referredDiscountBps": { "minimum": 0, "maximum": 10000, "type": "integer" }, "minimumRewardUsdCents": { "minimum": 0, "type": "integer" }, "earningStartsAt": { "format": "date-time", "type": "string" }, "earningEndsAt": { "format": "date-time", "type": "string" }, "revokedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "ended" ] }, { "type": "string", "enum": [ "expired" ] } ] } }, "required": [ "referrerName", "referrerShareBps", "referredDiscountBps", "minimumRewardUsdCents", "earningStartsAt", "earningEndsAt", "revokedAt", "status" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/referrals/summary": { "get": { "operationId": "getReferralsMadeSummary", "tags": [ "Account Management" ], "description": "Return aggregate referral counts and successfully paid reward value without identifying referred accounts or their activity.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalReferrals": { "minimum": 0, "type": "integer" }, "activeReferrals": { "minimum": 0, "type": "integer" }, "totalEarnedUsd": { "anyOf": [ { "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "type": "string" }, { "type": "null" } ] } }, "required": [ "totalReferrals", "activeReferrals", "totalEarnedUsd" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/referrals/profile": { "post": { "operationId": "getOrCreateReferralProfile", "tags": [ "Account Management" ], "description": "Return the account's active referral profile, creating its standard member profile on first use.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "pattern": "^[0-9a-f]{24}$", "type": "string" }, "referrerName": { "maxLength": 255, "type": "string" }, "referrerShareBps": { "minimum": 1, "maximum": 10000, "type": "integer" }, "referredDiscountBps": { "minimum": 0, "maximum": 10000, "type": "integer" }, "earningDurationDays": { "minimum": 1, "type": "integer" }, "minimumRewardUsdCents": { "minimum": 0, "type": "integer" } }, "required": [ "code", "referrerName", "referrerShareBps", "referredDiscountBps", "earningDurationDays", "minimumRewardUsdCents" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 60 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/pool/state": { "get": { "operationId": "getPoolState", "tags": [ "Transact" ], "description": "Get the current incognito pool state for an account and token. Returns the Merkle tree, ASP leaves, and your commitments — everything the client needs to build ZK withdrawal proofs.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": true, "description": "Chain ID of the pool" }, { "schema": { "type": "string" }, "in": "query", "name": "token", "required": true, "description": "Token address accepted by the pool (0x...)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "deposit" ] }, { "type": "string", "enum": [ "withdraw" ] } ] }, "in": "query", "name": "purpose", "required": false, "description": "When set to withdraw, the route returns POOL_STATE_REFRESHING unless proof inputs are ready." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "leaves": { "description": "State tree leaves in insertion order (stringified bigints)", "type": "array", "items": { "type": "string" } }, "currentRoot": { "description": "Current Merkle root (stringified bigint)", "type": "string" }, "treeSize": { "description": "Number of leaves in the tree", "type": "number" }, "aspLeaves": { "description": "ASP-approved labels. In dev: from DB. In staging/production: verified against Entrypoint.latestRoot before being served.", "type": "array", "items": { "type": "string" } }, "spentNullifiers": { "description": "All spent nullifiers from Withdrawn events — used for spent detection and change commitment discovery", "type": "array", "items": { "type": "object", "properties": { "nullifierHash": { "description": "Spent nullifier hash (stringified bigint)", "type": "string" }, "withdrawnValue": { "description": "Withdrawn amount in wei (stringified bigint)", "type": "string" }, "newCommitment": { "description": "Change commitment hash (stringified bigint)", "type": "string" } }, "required": [ "nullifierHash", "withdrawnValue", "newCommitment" ] } }, "nextDepositIndex": { "description": "Next available deposit index for this account — use for precommitment derivation", "type": "number" }, "commitments": { "description": "This account's unspent pool commitments", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Commitment DB ID", "type": "string" }, "depositIndex": { "type": "number" }, "withdrawalIndex": { "type": "number" }, "commitment": { "description": "On-chain commitment hash", "type": "string" }, "label": { "description": "On-chain label", "type": "string" }, "value": { "description": "Commitment value in wei", "type": "string" }, "withdrawals": { "type": "array", "items": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "quoteId": { "format": "uuid", "description": "Reference for this withdrawal activity", "type": "string" }, "amount": { "description": "Net recipient amount in token base units; null when unavailable for this balance", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "withdrawnAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "quoteId", "amount", "withdrawnAt" ] } }, "originalDeposit": { "description": "Original deposit details, preserved after partial withdrawals; null when unavailable", "anyOf": [ { "type": "object", "properties": { "quoteId": { "format": "uuid", "description": "Original deposit activity reference", "type": "string" }, "value": { "description": "Original net amount added to the pool, after deposit fees, in token base units", "type": "string" }, "depositedAt": { "description": "Original deposit chain timestamp, or recorded confirmation time; null when unavailable", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "value", "depositedAt" ] }, { "type": "null" } ] }, "aspStatus": { "description": "ASP approval status", "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] } ] } }, "required": [ "id", "depositIndex", "withdrawalIndex", "commitment", "label", "value", "aspStatus" ] } } }, "required": [ "leaves", "currentRoot", "treeSize", "spentNullifiers", "nextDepositIndex", "commitments" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/pool/commitments": { "get": { "operationId": "getPoolCommitments", "tags": [ "Transact" ], "description": "Get this account's current incognito commitments for a supported pool without loading Merkle proof state.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "chainId", "required": true, "description": "Chain ID of the pool" }, { "schema": { "type": "string" }, "in": "query", "name": "token", "required": true, "description": "Token address accepted by the pool (0x...)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "commitments": { "description": "This account's unspent pool commitments", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Commitment DB ID", "type": "string" }, "depositIndex": { "type": "number" }, "withdrawalIndex": { "type": "number" }, "commitment": { "description": "On-chain commitment hash", "type": "string" }, "label": { "description": "On-chain label", "type": "string" }, "value": { "description": "Commitment value in wei", "type": "string" }, "withdrawals": { "type": "array", "items": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "quoteId": { "format": "uuid", "description": "Reference for this withdrawal activity", "type": "string" }, "amount": { "description": "Net recipient amount in token base units; null when unavailable for this balance", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "withdrawnAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "quoteId", "amount", "withdrawnAt" ] } }, "originalDeposit": { "description": "Original deposit details, preserved after partial withdrawals; null when unavailable", "anyOf": [ { "type": "object", "properties": { "quoteId": { "format": "uuid", "description": "Original deposit activity reference", "type": "string" }, "value": { "description": "Original net amount added to the pool, after deposit fees, in token base units", "type": "string" }, "depositedAt": { "description": "Original deposit chain timestamp, or recorded confirmation time; null when unavailable", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "value", "depositedAt" ] }, { "type": "null" } ] }, "aspStatus": { "description": "ASP approval status", "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "declined" ] } ] } }, "required": [ "id", "depositIndex", "withdrawalIndex", "commitment", "label", "value", "aspStatus" ] } } }, "required": [ "commitments" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/pool/commitments/reconcile-asp-decline": { "post": { "operationId": "reconcilePoolCommitmentAspDecline", "tags": [ "Transact" ], "description": "Confirm that Privacy Pools explicitly declined a previously approved commitment, mark it recoverable, and release its unused withdrawal quote.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "commitmentId": { "format": "uuid", "description": "Selected pool commitment ID", "type": "string" }, "quoteId": { "format": "uuid", "description": "Unused pool-withdraw quote ID", "type": "string" } }, "required": [ "commitmentId", "quoteId" ] } } }, "required": true }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "accountId", "required": true, "description": "Account ID" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "code": { "type": "string", "enum": [ "POOL_DEPOSIT_DECLINED_AFTER_APPROVAL" ] }, "message": { "type": "string" } }, "required": [ "success", "code", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Conflict", "type": "string" }, "message": { "type": "string" }, "code": { "example": "QUOTE_LOCK_CONFLICT", "type": "string" }, "resolvedAddress": { "type": "string" }, "matchedAddress": { "type": "string" }, "matchedPrefixCharsCount": { "type": "integer" }, "matchedSuffixCharsCount": { "type": "integer" }, "matchSource": { "type": "string" }, "contactName": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/cloakie/verify": { "post": { "operationId": "verifyCloakieDeposit", "tags": [ "Cloakie" ], "description": "Verify Cloakie NFTs at an address belonging to this account on Base. Records verified deposits and activates the fee waiver. Returns only deposits verified at the supplied address.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "depositAddress": { "description": "Address in this account holding the Cloakie", "type": "string" } }, "required": [ "depositAddress" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "deposits": { "type": "array", "items": { "type": "object", "properties": { "depositAddress": { "type": "string" }, "tokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "depositAddress", "tokenId", "imageUrl" ] } } }, "required": [ "active", "deposits" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Service Unavailable", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SERVER_BUSY", "description": "Machine-readable reason, such as SERVER_BUSY or POOL_STATE_REFRESHING.", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/accounts/{accountId}/cloakie/withdraw": { "post": { "operationId": "withdrawCloakie", "tags": [ "Cloakie" ], "description": "Build an intent to transfer a Cloakie NFT from a deposit address back to the user. Returns intents and delegations for client signing.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "depositAddress": { "description": "Stealth address holding the Cloakie", "type": "string" }, "recipientAddress": { "description": "Address to send the Cloakie to", "type": "string" }, "tokenId": { "description": "Token ID of the Cloakie to withdraw (required if multiple at same address)", "type": "string" } }, "required": [ "depositAddress", "recipientAddress" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "eoa": { "type": "string" }, "executionData": { "type": "string" }, "nonce": { "type": "string" }, "derivationNonce": { "type": "string" }, "changeAddress": { "type": "object", "properties": { "address": { "type": "string" }, "derivationNonce": { "pattern": "^[0-9]{1,78}$", "type": "string" } }, "required": [ "address", "derivationNonce" ] }, "payer": { "type": "string" }, "paymentToken": { "type": "string" }, "paymentMaxAmount": { "type": "string" }, "combinedGas": { "type": "string" }, "encodedPreCalls": { "type": "array", "items": { "type": "string" } }, "encodedFundTransfers": { "type": "array", "items": { "type": "string" } }, "settler": { "type": "string" }, "expiry": { "type": "string" }, "isMultichain": { "type": "boolean" }, "funder": { "type": "string" }, "funderSignature": { "type": "string" }, "settlerContext": { "type": "string" }, "paymentAmount": { "type": "string" }, "paymentRecipient": { "type": "string" }, "paymentSignature": { "type": "string" }, "supportedAccountImplementation": { "type": "string" }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" } }, "required": [ "name", "version", "chainId", "verifyingContract" ] }, "types": { "description": "EIP-712 type definitions" }, "primaryType": { "type": "string", "enum": [ "Intent" ] } }, "required": [ "chainId", "eoa", "executionData", "nonce", "derivationNonce", "payer", "paymentToken", "paymentMaxAmount", "combinedGas", "encodedPreCalls", "encodedFundTransfers", "settler", "expiry", "isMultichain", "funder", "funderSignature", "settlerContext", "paymentAmount", "paymentRecipient", "paymentSignature", "supportedAccountImplementation", "domain", "types", "primaryType" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number" }, "address": { "type": "string" }, "contractAddress": { "type": "string" }, "derivationNonce": { "type": "number" }, "authorizationNonce": { "type": "number" } }, "required": [ "chainId", "address", "contractAddress", "derivationNonce", "authorizationNonce" ] } }, "expiresAt": { "type": "string" }, "signature": { "type": "string" }, "depositAddress": { "type": "string" }, "recipientAddress": { "type": "string" }, "tokenId": { "type": "string" } }, "required": [ "quoteId", "intents", "delegations", "expiresAt", "signature", "depositAddress", "recipientAddress", "tokenId" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Unauthorized", "type": "string" }, "message": { "type": "string" }, "code": { "example": "UNAUTHORIZED", "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/simulate": { "post": { "operationId": "simulateTransaction", "tags": [ "Simulation" ], "description": "Simulate a transaction to preview asset changes before signing.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "chainId": { "description": "Chain ID", "type": "number" }, "from": { "description": "Sender address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "description": "Target address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "value": { "description": "Value in wei (decimal string)", "pattern": "^[0-9]+$", "type": "string" }, "data": { "description": "Calldata (hex string)", "pattern": "^0x[a-fA-F0-9]*$", "type": "string" } }, "required": [ "chainId", "from", "to", "value", "data" ] }, { "additionalProperties": false, "type": "object", "properties": { "chainId": { "description": "Chain ID", "type": "number" }, "from": { "description": "Sender address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "calls": { "description": "Calls to execute consecutively against shared simulation state", "minItems": 1, "maxItems": 50, "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "to": { "description": "Target address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "value": { "description": "Value in wei (decimal string)", "pattern": "^[0-9]+$", "type": "string" }, "data": { "description": "Calldata (hex string)", "pattern": "^0x[a-fA-F0-9]*$", "type": "string" } }, "required": [ "to", "value", "data" ] } } }, "required": [ "chainId", "from", "calls" ] }, { "additionalProperties": false, "type": "object", "properties": { "chainId": { "description": "Chain ID", "type": "number" }, "transactions": { "description": "Ordered calls from every signer in an exact product quote", "minItems": 1, "maxItems": 100, "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "from": { "description": "Sender address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "intentIndex": { "description": "Signed intent position", "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "description": "Call position within the intent", "minimum": 0, "maximum": 49, "type": "integer" }, "to": { "description": "Target address", "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "value": { "description": "Value in wei (decimal string)", "pattern": "^[0-9]+$", "type": "string" }, "data": { "description": "Calldata (hex string)", "pattern": "^0x[a-fA-F0-9]*$", "type": "string" } }, "required": [ "from", "intentIndex", "callIndex", "to", "value", "data" ] } }, "effectCalls": { "description": "Exact signed quote calls whose effects belong in the compact preview", "minItems": 1, "maxItems": 100, "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "intentIndex": { "description": "Signed intent position", "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "description": "Call position within the intent", "minimum": 0, "maximum": 49, "type": "integer" } }, "required": [ "intentIndex", "callIndex" ] } } }, "required": [ "chainId", "transactions", "effectCalls" ] } ] } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "local" ] }, { "type": "string", "enum": [ "tenderly" ] }, { "type": "string", "enum": [ "rpc" ] } ] }, "gasUsed": { "type": "number" }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient-token-balance" ] }, { "type": "string", "enum": [ "reverted" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "assetChangesComplete": { "type": "boolean" }, "assetChanges": { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "intentIndex": { "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "minimum": 0, "maximum": 49, "type": "integer" }, "type": { "anyOf": [ { "type": "string", "enum": [ "transfer" ] }, { "type": "string", "enum": [ "approval" ] }, { "type": "string", "enum": [ "native" ] } ] }, "token": { "type": "object", "properties": { "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "symbol": { "maxLength": 32, "type": "string" }, "decimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "name": { "maxLength": 80, "type": "string" } }, "required": [ "address" ] }, "from": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "amount": { "maxLength": 120, "type": "string" }, "rawAmount": { "maxLength": 120, "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "type", "from", "to", "amount", "rawAmount" ] }, { "type": "object", "properties": { "intentIndex": { "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "minimum": 0, "maximum": 49, "type": "integer" }, "contractAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "from": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "type": { "type": "string", "enum": [ "erc721" ] }, "tokenId": { "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 78, "type": "string" } }, "required": [ "contractAddress", "from", "to", "type", "tokenId" ] }, { "type": "object", "properties": { "intentIndex": { "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "minimum": 0, "maximum": 49, "type": "integer" }, "contractAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "from": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "type": { "type": "string", "enum": [ "erc1155" ] }, "tokenId": { "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 78, "type": "string" }, "quantity": { "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 78, "type": "string" } }, "required": [ "contractAddress", "from", "to", "type", "tokenId", "quantity" ] }, { "type": "object", "properties": { "intentIndex": { "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "minimum": 0, "maximum": 49, "type": "integer" }, "contractAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "from": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "type": { "type": "string", "enum": [ "erc721-approval" ] }, "tokenId": { "pattern": "^(0|[1-9][0-9]*)$", "maxLength": 78, "type": "string" } }, "required": [ "contractAddress", "from", "to", "type", "tokenId" ] }, { "type": "object", "properties": { "intentIndex": { "minimum": 0, "maximum": 50, "type": "integer" }, "callIndex": { "minimum": 0, "maximum": 49, "type": "integer" }, "contractAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "from": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "to": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "type": { "type": "string", "enum": [ "nft-approval-for-all" ] }, "approved": { "type": "boolean" } }, "required": [ "contractAddress", "from", "to", "type", "approved" ] } ] } }, "error": { "type": "string" } }, "required": [ "success", "provider", "assetChangesComplete", "assetChanges" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad request", "type": "string" }, "message": { "type": "string" }, "code": { "example": "BAD_REQUEST", "type": "string" }, "available": { "description": "Available balance in smallest unit (for INSUFFICIENT_BALANCE)", "example": "0", "type": "string" }, "tokenSymbol": { "description": "Token symbol for the balance that caused the quote error", "example": "ETH", "type": "string" }, "tokenAddress": { "description": "Token address for the balance that caused the quote error", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "type": "string" }, "tokenDecimals": { "description": "Token decimals for smallest-unit quote error amounts", "example": 18, "type": "number" }, "minAmount": { "description": "Human-readable minimum amount (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.00036 ETH", "type": "string" }, "maxSendable": { "description": "Maximum amount available after fees. Human-readable for WITHDRAWAL_AMOUNT_TOO_SMALL; smallest unit for INSUFFICIENT_FUNDS_FOR_FEES.", "example": "0.018 ETH", "type": "string" }, "feeEstimate": { "description": "Estimated fee in smallest unit (for INSUFFICIENT_FUNDS_FOR_FEES)", "example": "1000000000000000", "type": "string" }, "required": { "description": "Requested amount plus estimated fee in smallest unit", "example": "1010000000000000000", "type": "string" }, "shortfall": { "description": "Amount by which the request exceeds the fee-adjusted maximum", "example": "1000000000000000", "type": "string" }, "spendableCount": { "description": "Spendable count used for the fee-adjusted maximum", "example": 1, "type": "number" }, "maxInputs": { "description": "Maximum input count allowed by the selector", "example": 50, "type": "number" }, "selectedAmount": { "description": "Selected pool balance total considered for the quote (for WITHDRAWAL_AMOUNT_TOO_SMALL)", "example": "0.02 ETH", "type": "string" }, "relayFee": { "description": "Estimated relay fee for the selected withdrawal balances", "example": "0.0042 ETH", "type": "string" }, "feeLimit": { "description": "Maximum relay fee allowed for the requested withdrawal amount", "example": "0.001 ETH", "type": "string" }, "maxRelayFeeBPS": { "description": "Maximum relay fee basis points allowed by the pool", "example": 1000, "type": "number" }, "requiredRelayFeeBPS": { "description": "Required relay fee basis points for the requested withdrawal", "example": "1523", "type": "string" }, "selectedCount": { "description": "Number of selected pool balances considered by the quote", "example": 2, "type": "number" }, "resolvedAddress": { "description": "Exact resolved destination address requiring acknowledgement for a contract recipient", "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/function-signatures": { "post": { "operationId": "lookupFunctionSignatures", "tags": [ "Utilities" ], "description": "Batch-resolve 4-byte function selectors to human-readable signatures. Uses a server-side cache backed by Sourcify's 4byte signature database.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "selectors": { "minItems": 1, "maxItems": 20, "description": "Array of 4-byte hex selectors (e.g. [\"0xa9059cbb\"])", "type": "array", "items": { "pattern": "^0x[a-fA-F0-9]{8}$", "type": "string" } } }, "required": [ "selectors" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "signatures": { "description": "Map of selector → signature (null if unknown or ambiguous)", "type": "object", "additionalProperties": { "anyOf": [ { "minLength": 1, "maxLength": 256, "type": "string" }, { "type": "null" } ] } }, "candidates": { "description": "Map of selector → bounded candidate set for safe client-side calldata decoding", "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "signatures": { "maxItems": 20, "type": "array", "items": { "minLength": 1, "maxLength": 256, "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "signatures", "truncated" ] }, { "type": "null" } ] } } }, "required": [ "signatures", "candidates" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Forbidden", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/clear-signing/descriptor": { "get": { "operationId": "getClearSigningDescriptor", "tags": [ "Utilities" ], "description": "Resolve an ERC-7730 descriptor from Cloaked’s pinned, validated registry snapshot for a specific chain, contract, and calldata or EIP-712 format.", "parameters": [ { "schema": { "minimum": 1, "type": "integer" }, "in": "query", "name": "chainId", "required": true }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "calldata" ] }, { "type": "string", "enum": [ "eip712" ] } ] }, "in": "query", "name": "kind", "required": true }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "caller", "required": false }, { "schema": { "pattern": "^0x[a-fA-F0-9]{8}$", "type": "string" }, "in": "query", "name": "selector", "required": false }, { "schema": { "minLength": 1, "maxLength": 8192, "type": "string" }, "in": "query", "name": "formatKey", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string", "enum": [ "calldata" ] }, { "type": "string", "enum": [ "eip712" ] } ] }, "descriptor": { "type": "object", "additionalProperties": {} }, "source": { "type": "object", "properties": { "registry": { "anyOf": [ { "type": "string", "enum": [ "ethereum" ] }, { "type": "string", "enum": [ "cloaked" ] } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "official" ] }, { "type": "string", "enum": [ "pending-review" ] } ] }, "repository": { "type": "string" }, "commit": { "pattern": "^[0-9a-f]{40}$", "type": "string" }, "path": { "type": "string" }, "url": { "format": "uri", "type": "string" }, "descriptorHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "pullRequest": { "format": "uri", "type": "string" } }, "required": [ "registry", "status", "repository", "commit", "path", "url", "descriptorHash" ] }, "binding": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "contract-standard" ] }, "standard": { "type": "string", "enum": [ "erc20" ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "pattern": "^0x[a-f0-9]{40}$", "type": "string" }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trusted-token-catalog" ] }, "onchainDecimals": { "minimum": 0, "maximum": 255, "type": "integer" }, "catalogSources": { "minItems": 1, "maxItems": 4, "uniqueItems": true, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "clanker" ] }, { "type": "string", "enum": [ "coingecko" ] }, { "type": "string", "enum": [ "pons" ] }, { "type": "string", "enum": [ "pools" ] } ] } } }, "required": [ "kind", "onchainDecimals", "catalogSources" ] } }, "required": [ "kind", "standard", "chainId", "address", "evidence" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "proxy-implementation" ] }, "evidenceVersion": { "type": "number", "enum": [ 2 ] }, "chainId": { "minimum": 1, "type": "integer" }, "proxyAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "caller": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "selector": { "pattern": "^0x[a-f0-9]{8}$", "type": "string" }, "proxyKind": { "anyOf": [ { "type": "string", "enum": [ "eip1967" ] }, { "type": "string", "enum": [ "beacon" ] }, { "type": "string", "enum": [ "safe" ] } ] }, "proxyCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "implementationAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "implementationCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "beaconAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "beaconCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "blockNumber": { "pattern": "^(?:0|[1-9][0-9]*)$", "type": "string" }, "blockHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "functionDeclaration": { "minLength": 1, "maxLength": 32768, "type": "string" }, "functionHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" } }, "required": [ "kind", "evidenceVersion", "chainId", "proxyAddress", "caller", "selector", "proxyKind", "proxyCodeHash", "implementationAddress", "implementationCodeHash", "blockNumber", "blockHash", "functionDeclaration", "functionHash" ] } ] } }, "required": [ "kind", "descriptor", "source" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 120 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/v1/clear-signing/sourcify-function": { "get": { "operationId": "getSourcifyFunction", "tags": [ "Utilities" ], "description": "Resolve the exact ABI function from source Sourcify matched to the current direct-contract runtime or a freshly proven proxy implementation.", "parameters": [ { "schema": { "minimum": 1, "type": "integer" }, "in": "query", "name": "chainId", "required": true }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "address", "required": true }, { "schema": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "in": "query", "name": "caller", "required": false }, { "schema": { "pattern": "^0x[a-fA-F0-9]{8}$", "type": "string" }, "in": "query", "name": "selector", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "evidenceVersion": { "type": "number", "enum": [ 1 ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "selector": { "pattern": "^0x[a-f0-9]{8}$", "type": "string" }, "contractKind": { "type": "string", "enum": [ "direct" ] }, "functionDeclaration": { "minLength": 1, "maxLength": 32768, "type": "string" }, "functionHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "runtimeCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "match": { "anyOf": [ { "type": "string", "enum": [ "match" ] }, { "type": "string", "enum": [ "exact_match" ] } ] }, "runtimeMatch": { "anyOf": [ { "type": "string", "enum": [ "match" ] }, { "type": "string", "enum": [ "exact_match" ] } ] }, "sourceUrl": { "format": "uri", "type": "string" } }, "required": [ "evidenceVersion", "chainId", "address", "selector", "contractKind", "functionDeclaration", "functionHash", "runtimeCodeHash", "match", "runtimeMatch", "sourceUrl" ] }, { "type": "object", "properties": { "evidenceVersion": { "type": "number", "enum": [ 2 ] }, "chainId": { "minimum": 1, "type": "integer" }, "address": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "caller": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "selector": { "pattern": "^0x[a-f0-9]{8}$", "type": "string" }, "contractKind": { "type": "string", "enum": [ "proxy" ] }, "proxyKind": { "anyOf": [ { "type": "string", "enum": [ "eip1967" ] }, { "type": "string", "enum": [ "beacon" ] }, { "type": "string", "enum": [ "safe" ] } ] }, "proxyCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "implementationAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "implementationCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "beaconAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "beaconCodeHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "blockNumber": { "pattern": "^(?:0|[1-9][0-9]*)$", "type": "string" }, "blockHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "functionDeclaration": { "minLength": 1, "maxLength": 32768, "type": "string" }, "functionHash": { "pattern": "^0x[a-fA-F0-9]{64}$", "type": "string" }, "match": { "anyOf": [ { "type": "string", "enum": [ "match" ] }, { "type": "string", "enum": [ "exact_match" ] } ] }, "runtimeMatch": { "anyOf": [ { "type": "string", "enum": [ "match" ] }, { "type": "string", "enum": [ "exact_match" ] } ] }, "sourceUrl": { "format": "uri", "type": "string" } }, "required": [ "evidenceVersion", "chainId", "address", "caller", "selector", "contractKind", "proxyKind", "proxyCodeHash", "implementationAddress", "implementationCodeHash", "blockNumber", "blockHash", "functionDeclaration", "functionHash", "match", "runtimeMatch", "sourceUrl" ] } ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Not found", "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Too Many Requests", "type": "string" }, "message": { "example": "Rate limit exceeded. Maximum 120 requests per 1 minute.", "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "example": "Bad Gateway", "type": "string" }, "message": { "type": "string" }, "code": { "example": "SWAP_UNAVAILABLE", "type": "string" } }, "required": [ "error", "message" ] } } } } } } } }, "servers": [ { "url": "https://api.clkd.xyz", "description": "Production" }, { "url": "https://api-stg.clkd.xyz", "description": "Staging" } ], "tags": [ { "name": "Authentication", "description": "SIWE authentication and server key discovery. **Important:** the address used for authentication must be the address derived from your private spending key (`privateKeyToAccount(p_spend)`), NOT your connected wallet address. The server identity is this derived auth address — your wallet address never touches the server." }, { "name": "Account Management", "description": "Account creation, signers, subdomains, and setup" }, { "name": "Receive", "description": "Payment address generation and ENS resolution" }, { "name": "Balance & Activity", "description": "Balance queries, transaction history, and supported tokens" }, { "name": "Transact", "description": "Sending, swapping, bridging, converting to incognito, and cashing out all follow the same flow: get a quote, then submit." }, { "name": "Incognito Send", "description": "Send from incognito balances. The sender generates ZK proofs client-side — the server relays the transaction on-chain." }, { "name": "Cloakie", "description": "Cloakie NFT verification and withdrawal" } ] }