{ "openapi": "3.1.0", "paths": { "/v1/accounts": { "get": { "description": "Retrieve all accounts for your workspace with optional filtering and pagination.", "operationId": "account_findAll", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "Filter by account type", "schema": { "enum": [ "fiat_bank", "stablecoin_ethereum", "stablecoin_solana", "stablecoin_stellar", "ledger" ], "type": "string" } }, { "name": "tenant_id", "required": false, "in": "query", "description": "Filter by tenant ID", "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "name": "counterparty_id", "required": false, "in": "query", "description": "Filter by counterparty ID", "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "name": "entity_type", "required": false, "in": "query", "description": "Filter by entity type (e.g. sub_org for workspace-level)", "schema": { "type": "string", "enum": ["sub_org", "counterparty", "tenant"] } }, { "name": "search", "required": false, "in": "query", "description": "Search by account name", "schema": { "type": "string" } }, { "name": "is_managed", "required": false, "in": "query", "description": "Filter by managed status: 'true' for managed wallets only, 'false' for unmanaged wallets only, omit for all accounts", "schema": { "enum": ["true", "false"], "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked sensitive fields (e.g., bank account number)", "schema": { "type": "boolean" } }, { "name": "compliance_accepted", "required": false, "in": "query", "description": "Filter ledger accounts by compliance status: 'true' returns only ledgers with ACCEPTED compliance state", "schema": { "type": "boolean" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-based)", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page (default: 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Accounts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListResponse" }, "example": { "data": [ { "id": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "type": "fiat_bank", "name": "Operating Account - EU", "bank_name": "Chase Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "CHASUS33", "created_at": "2024-03-02T14:30:00.000Z", "updated_at": "2024-03-02T14:30:00.000Z", "bank_account_number": "•••6789" }, { "id": "7a3d8f2e-6b4c-4a91-b8e5-2f9c1d7e3a0b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": null, "type": "stablecoin_ethereum", "name": "Treasury Wallet - Ethereum", "crypto_wallet_address": "0x742d35CC6634C0532925a3B844BC9e7595f8fe0B", "is_managed": true, "assets": [ { "currency": "USDC", "network": "POLYGON", "available_balance": "0" }, { "currency": "USDT", "network": "POLYGON", "available_balance": "0" } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 2, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all accounts", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/accounts/banks": { "post": { "description": "Create a new fiat bank account for your workspace, tenant, or counterparty.\n\n**Security:** The `bank_account_number` field is encrypted and stored securely in a vault. It will never be returned in API responses.\n\n**Ownership:** Use `tenant_id` OR `counterparty_id` to link the account. Omit both for a workspace-level account.", "operationId": "account_createBankAccount", "parameters": [], "requestBody": { "required": true, "description": "Bank account data. The bank_account_number field is SECURELY ENCRYPTED and stored in vault.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankAccountRequestDto" }, "examples": { "workspace": { "summary": "Create a workspace-level bank account", "value": { "name": "Workspace Operating Account", "bank_name": "JPMorgan Chase Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "CHASUS33", "bank_account_number": "1234567890" } }, "counterparty": { "summary": "Create a bank account for a counterparty", "value": { "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "name": "Supplier Payment Account - EU", "bank_name": "Deutsche Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "DEUTDEFF", "bank_account_number": "DE89370400440532013000" } }, "tenant": { "summary": "Create a bank account for a tenant", "value": { "tenant_id": "7a1f5c9e-3b2d-4e68-b0a4-6e9c1f3d8a2b", "name": "Client Treasury Account", "bank_name": "Bank of America", "bank_code_type": "ROUTING", "bank_identifier_code": "026009593", "bank_account_number": "987654321" } } } } } }, "responses": { "201": { "description": "Bank account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankAccountResponseDto" }, "example": { "data": { "id": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "type": "fiat_bank", "name": "Operating Account - EU", "bank_name": "Chase Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "CHASUS33", "created_at": "2024-03-02T14:30:00.000Z", "updated_at": "2024-03-02T14:30:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new bank account", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/accounts/ledgers": { "post": { "description": "Create a ledger account linked to an external liquidity provider.\n\n**Supported Providers:**\n- `CIRCLE_MINT`: Circle Mint USDC accounts for institutional settlement\n- `KRAKEN`: Kraken exchange accounts for cryptocurrency liquidity\n\nLedger accounts are virtual accounts managed by the provider. They enable fast settlement without on-chain transactions.\n\n**Ownership:** Use `tenant_id` OR `counterparty_id` to link the account. Omit both for a workspace-level ledger account.", "operationId": "account_createLedgerAccount", "parameters": [], "requestBody": { "required": true, "description": "Ledger account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLedgerAccountRequestDto" }, "examples": { "circle_tenant": { "summary": "Create a Circle Mint USDC ledger account for a tenant", "value": { "tenant_id": "7a1f5c9e-3b2d-4e68-b0a4-6e9c1f3d8a2b", "name": "Circle Settlement Account", "provider": "CIRCLE_MINT" } }, "circle_counterparty": { "summary": "Create a Circle Mint USDC ledger account for a counterparty", "value": { "counterparty_id": "6f1c4a8e-2d7b-4930-b5e2-9a3f0c7d1b6e", "name": "Counterparty Circle Account", "provider": "CIRCLE_MINT" } }, "kraken_counterparty": { "summary": "Create a Kraken ledger account for a counterparty", "value": { "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "name": "Supplier Kraken Account", "provider": "KRAKEN" } } } } } }, "responses": { "201": { "description": "Ledger account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLedgerAccountResponseDto" }, "example": { "data": { "id": "770e8400-e29b-41d4-a716-446655440006", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": null, "type": "ledger", "name": "Circle Settlement Account", "provider": "CIRCLE_MINT", "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new ledger account", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/accounts/wallets": { "post": { "description": "Create a new stablecoin wallet account.\n\n**Supported Networks:**\n- `stablecoin_ethereum` - Ethereum/Polygon stablecoin wallet\n- `stablecoin_solana` - Solana stablecoin wallet\n- `stablecoin_stellar` - Stellar stablecoin wallet\n\n**Wallet Types:**\n- **Managed** (`is_managed=true`) - Tesser-managed wallet, requires `signature`\n- **Unmanaged** (`is_managed=false`, default) - External wallet, requires `wallet_address`\n\n**Ownership:** Optionally link to a tenant or counterparty using `tenant_id` or `counterparty_id`.", "operationId": "account_createWalletAccount", "parameters": [], "requestBody": { "required": true, "description": "Wallet account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAccountRequestDto" }, "examples": { "managed": { "summary": "Managed wallet (Tesser-managed)", "value": { "name": "Treasury Wallet (Omnibus)", "type": "stablecoin_ethereum", "is_managed": true, "signature": "eyJwdWJsaWNLZXkiOiJwdWJfZXhhbXBsZSIsInNpZ25hdHVyZSI6InNpZ19leGFtcGxlIiwic2NoZW1lIjoiRUQyNTUxOSJ9" } }, "unmanaged": { "summary": "Unmanaged wallet (external address)", "value": { "name": "External Partner Wallet", "type": "stablecoin_ethereum", "is_managed": false, "wallet_address": "0x742d35CC6634C0532925a3B844BC9e7595f8fe0B", "counterparty_id": "550e8400-e29b-41d4-a716-446655440002" } } } } } }, "responses": { "201": { "description": "Wallet account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAccountResponseDto" }, "example": { "data": { "id": "7a3d8f2e-6b4c-4a91-b8e5-2f9c1d7e3a0b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": null, "type": "stablecoin_ethereum", "name": "Treasury Wallet - Ethereum", "crypto_wallet_address": "0x742d35CC6634C0532925a3B844BC9e7595f8fe0B", "is_managed": true, "assets": [ { "currency": "USDC", "network": "POLYGON", "available_balance": "0" }, { "currency": "USDT", "network": "POLYGON", "available_balance": "0" } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new wallet account", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/accounts/{id}": { "get": { "description": "Retrieve a specific account by its unique identifier.", "operationId": "account_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Account ID (UUID)", "schema": { "example": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked secure fields (e.g., bank account number)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" }, "example": { "data": { "id": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "type": "fiat_bank", "name": "Operating Account - EU", "bank_name": "Chase Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "CHASUS33", "created_at": "2024-03-02T14:30:00.000Z", "updated_at": "2024-03-02T14:30:00.000Z", "bank_account_number": "•••6789" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get an account by ID", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "patch": { "description": "Update an existing account's information.", "operationId": "account_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Account ID (UUID)", "schema": { "example": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequestDto" }, "examples": { "default": { "summary": "Update account name", "value": { "name": "Updated Operating Account" } } } } } }, "responses": { "200": { "description": "Account updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountResponseDto" }, "example": { "data": { "id": "8f3b1e7c-9a2d-4f58-b6c0-4e7d2a9f1b3c", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "tenant_id": null, "counterparty_id": "2a7e1c9f-4b3d-4a82-b6e0-8f5c2d1a9b3e", "type": "fiat_bank", "name": "Updated Operating Account", "bank_name": "Chase Bank", "bank_code_type": "SWIFT", "bank_identifier_code": "CHASUS33", "created_at": "2024-03-02T14:30:00.000Z", "updated_at": "2024-03-01T12:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update an account", "tags": ["Accounts"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/admin/invitations": { "post": { "operationId": "admin_createInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationRequestDto" } } } }, "responses": { "201": { "description": "Invitation sent successfully" }, "401": { "description": "Invalid admin secret" } }, "summary": "Create an invitation for a new user", "tags": ["Admin"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] } }, "/v1/currencies": { "get": { "description": "Retrieve list of all supported currencies (crypto and fiat). Returns an array with currency name, key, decimals, and network information.", "operationId": "currency_getCurrencies", "parameters": [], "responses": { "200": { "description": "Successfully retrieved available currencies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrenciesResponse" }, "example": { "data": [ { "name": "Circle USD", "key": "USDC", "decimals": 6, "network": "BASE" }, { "name": "Tether USD", "key": "USDT", "decimals": 6, "network": "BASE" }, { "name": "Circle USD", "key": "USDC", "decimals": 6, "network": "ETHEREUM" }, { "name": "Tether USD", "key": "USDT", "decimals": 6, "network": "ETHEREUM" }, { "name": "Circle USD", "key": "USDC", "decimals": 6, "network": "POLYGON" }, { "name": "Tether USD", "key": "USDT", "decimals": 6, "network": "POLYGON" }, { "name": "Circle USD", "key": "USDC", "decimals": 6, "network": "STELLAR" }, { "name": "USD", "key": "USD", "decimals": 2, "network": null } ] } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get available currencies", "tags": ["Currencies"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/entities/counterparties": { "post": { "description": "Create a new counterparty for your workspace or a specific tenant.", "operationId": "counterparty_create", "parameters": [], "requestBody": { "required": true, "description": "Counterparty data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCounterpartyRequestDto" }, "examples": { "individual": { "summary": "Create an individual counterparty", "value": { "classification": "individual", "individual_first_name": "John", "individual_last_name": "Doe", "individual_address_country": "US", "individual_date_of_birth": "1980-01-01", "individual_national_identification_number": "123456789", "individual_street_address1": "123 Main St", "individual_street_address2": "Apt 4B", "individual_city": "New York", "individual_state": "NY", "individual_postal_code": "10001" } }, "business": { "summary": "Create a business counterparty", "value": { "classification": "business", "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_legal_entity_identifier": "1234567890" } }, "business_with_tenant": { "summary": "Create a counterparty assigned to a tenant", "description": "Use tenant_id to assign the counterparty to a specific tenant. Only workspace-level API keys can specify tenant_id. Tenant API keys automatically assign counterparties to their tenant.", "value": { "classification": "business", "tenant_id": "4e8c2a6f-1b9d-4f37-a5e0-7c3b8d2f1a9e", "business_legal_name": "Tenant Customer Corp", "business_dba": "TenantCust", "business_address_country": "US", "business_street_address1": "789 Partner Lane", "business_city": "Chicago", "business_state": "IL", "business_postal_code": "60601" } } } } } }, "responses": { "201": { "description": "Counterparty created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCounterpartyResponseDto" }, "example": { "data": { "id": "c7d8e9f0-1a2b-3c4d-5e6f-789012345678", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "classification": "individual", "tenant_id": null, "individual_first_name": "John", "individual_last_name": "Doe", "individual_address_country": "US", "individual_date_of_birth": "1980-01-01", "individual_national_identification_number": "123456789", "individual_street_address1": "123 Main St", "individual_street_address2": "Apt 4B", "individual_city": "New York", "individual_state": "NY", "individual_postal_code": "10001", "business_legal_name": null, "business_dba": null, "business_address_country": null, "business_street_address1": null, "business_street_address2": null, "business_city": null, "business_state": null, "business_legal_entity_identifier": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new counterparty", "tags": ["Counterparties"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "get": { "description": "Retrieve all counterparties for your workspace or a specific tenant.", "operationId": "counterparty_findAll", "parameters": [ { "name": "classification", "required": false, "in": "query", "description": "Filter by classification", "schema": { "enum": ["individual", "business"], "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search by name", "schema": { "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked vault data (address, DOB, national ID, legal entity identifier)", "schema": { "default": false, "type": "boolean" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-based)", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page (default: 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Counterparties retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyListResponse" }, "example": { "data": [ { "id": "6f1c4a8e-2d7b-4930-b5e2-9a3f0c7d1b6e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "classification": "business", "tenant_id": null, "individual_first_name": null, "individual_last_name": null, "individual_address_country": null, "individual_date_of_birth": null, "individual_national_identification_number": null, "individual_street_address1": null, "individual_street_address2": null, "individual_city": null, "individual_state": null, "individual_postal_code": null, "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_legal_entity_identifier": "1234567890", "created_at": "2024-02-01T14:00:00.000Z", "updated_at": "2024-02-01T14:00:00.000Z" }, { "id": "3e9a7c2f-1b8d-4e56-a0f3-5c2d8b1e9a7f", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "classification": "individual", "tenant_id": null, "individual_first_name": "John", "individual_last_name": "Doe", "individual_address_country": "US", "individual_date_of_birth": "1980-01-01", "individual_national_identification_number": "123456789", "individual_street_address1": "123 Main St", "individual_street_address2": "Apt 4B", "individual_city": "New York", "individual_state": "NY", "individual_postal_code": "10001", "business_legal_name": null, "business_dba": null, "business_address_country": null, "business_street_address1": null, "business_street_address2": null, "business_city": null, "business_state": null, "business_legal_entity_identifier": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 2, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all counterparties", "tags": ["Counterparties"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/entities/counterparties/{id}": { "get": { "description": "Retrieve a specific counterparty by its unique identifier.", "operationId": "counterparty_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Counterparty ID (UUID)", "schema": { "example": "d8e9f0a1-2b3c-4d5e-6f78-901234567890", "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked vault data (address, DOB, national ID, legal entity identifier)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Counterparty retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyResponseDto" }, "example": { "data": { "id": "d8e9f0a1-2b3c-4d5e-6f78-901234567890", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "classification": "business", "tenant_id": null, "individual_first_name": null, "individual_last_name": null, "individual_address_country": null, "individual_date_of_birth": null, "individual_national_identification_number": null, "individual_street_address1": null, "individual_street_address2": null, "individual_city": null, "individual_state": null, "individual_postal_code": null, "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_legal_entity_identifier": "1234567890", "created_at": "2024-02-01T14:00:00.000Z", "updated_at": "2024-02-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a counterparty by ID", "tags": ["Counterparties"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/entities/tenants": { "post": { "description": "Create a new tenant for your workspace. Tenants are business customers that can have their own counterparties and accounts.\n\nTenants can be assigned to counterparties to organize your workspace by customer.\n\n**Required fields:** business_legal_name", "operationId": "tenant_create", "parameters": [], "requestBody": { "required": true, "description": "Tenant data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequestDto" }, "examples": { "default": { "summary": "Create a tenant", "value": { "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_postal_code": "94105", "webhook_url": "https://acme.com/webhooks/tesser" } }, "minimal": { "summary": "Create a tenant (minimal)", "value": { "business_legal_name": "TechStart Inc" } } } } } }, "responses": { "201": { "description": "Tenant created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantResponseDto" }, "example": { "data": { "tenant": { "id": "0c6e3a9f-2b1d-4f84-a7e5-8d4c1b2f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "name": "Acme Co", "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "webhook_url": "https://acme.com/webhooks/tesser", "business_street_address1": null, "business_street_address2": null, "business_city": null, "business_state": null, "business_postal_code": null, "business_legal_entity_identifier": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z" } } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a new tenant", "tags": ["Tenants"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "get": { "description": "Retrieve all tenants for your workspace with optional search filtering and pagination.", "operationId": "tenant_findAll", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Search by name (legal name or DBA)", "schema": { "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked vault data (address, legal entity identifier)", "schema": { "type": "boolean" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-based)", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page (default: 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Tenants retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantListResponse" }, "example": { "data": [ { "id": "4e8c2a6f-1b9d-4f37-a5e0-7c3b8d2f1a9e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "name": "Acme Co", "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "webhook_url": "https://acme.com/webhooks/tesser", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_postal_code": "94105", "business_legal_entity_identifier": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }, { "id": "7a1f5c9e-3b2d-4e68-b0a4-6e9c1f3d8a2b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "name": "TechStart Inc", "business_legal_name": "TechStart Inc", "business_dba": null, "business_address_country": "CA", "webhook_url": null, "business_street_address1": "789 Startup Ave", "business_street_address2": null, "business_city": "Toronto", "business_state": "ON", "business_postal_code": "M5V 2T6", "business_legal_entity_identifier": null, "created_at": "2024-02-01T14:00:00.000Z", "updated_at": "2024-02-01T14:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 2, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "List all tenants", "tags": ["Tenants"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/entities/tenants/{id}": { "get": { "description": "Retrieve a specific tenant by its unique identifier.", "operationId": "tenant_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Tenant ID (UUID)", "schema": { "example": "4e8c2a6f-1b9d-4f37-a5e0-7c3b8d2f1a9e", "type": "string" } }, { "name": "include_secure", "required": false, "in": "query", "description": "Include masked vault data (address, legal entity identifier)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Tenant retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponseDto" }, "example": { "data": { "id": "4e8c2a6f-1b9d-4f37-a5e0-7c3b8d2f1a9e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "name": "Acme Co", "business_legal_name": "Acme Corporation", "business_dba": "Acme Co", "business_address_country": "US", "webhook_url": "https://acme.com/webhooks/tesser", "business_street_address1": "456 Corp Blvd", "business_street_address2": "Suite 200", "business_city": "San Francisco", "business_state": "CA", "business_postal_code": "94105", "business_legal_entity_identifier": null, "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a tenant by ID", "tags": ["Tenants"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/health": { "get": { "operationId": "app_getHealth", "parameters": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "gitSha": { "type": "string", "example": "abc123def456" }, "env": { "type": "string", "example": "local" } } } } } } }, "summary": "Health check endpoint", "tags": ["health"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] } }, "/v1/keys": { "post": { "description": "Creates an Auth0 M2M application and returns client credentials. Use these credentials to fetch access tokens from Auth0.", "operationId": "keys_createApiKey", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequestDto" } } } }, "responses": { "201": { "description": "The API key has been successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponseDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearer": [] } ], "summary": "Create a new API key", "tags": ["API Keys"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "get": { "operationId": "keys_listApiKeys", "parameters": [], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponseDto" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ], "summary": "List all API keys for the workspace", "tags": ["API Keys"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/keys/{id}": { "get": { "operationId": "keys_getApiKey", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "API key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDto" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "API key not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a specific API key", "tags": ["API Keys"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "delete": { "operationId": "keys_deleteApiKey", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "API key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiKeyResponseDto" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "API key not found" } }, "security": [ { "bearer": [] } ], "summary": "Delete an API key", "tags": ["API Keys"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/keys/{id}/revoke": { "put": { "description": "Deletes the Auth0 M2M application, instantly invalidating all tokens.", "operationId": "keys_revokeApiKey", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "API key ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key has been revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponseDto" } } } }, "400": { "description": "API key is already revoked" }, "401": { "description": "Unauthorized" }, "404": { "description": "API key not found" } }, "security": [ { "bearer": [] } ], "summary": "Revoke an API key", "tags": ["API Keys"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/networks": { "get": { "description": "Retrieve list of all supported blockchain networks. Returns an object with a data array containing network key and display name.", "operationId": "networks_getNetworks", "parameters": [], "responses": { "200": { "description": "Successfully retrieved available networks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworksResponse" }, "example": { "data": [ { "key": "BASE", "name": "Base" }, { "key": "ETHEREUM", "name": "Ethereum" }, { "key": "POLYGON", "name": "Polygon" } ] } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get available networks", "tags": ["Networks"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/organizations/risk-profile": { "patch": { "description": "Update the compliance risk profile for the authenticated user's organization. Available profiles:\n\n- **conservative**: Strictest screening, lowest risk tolerance\n- **balanced**: Moderate screening (default)\n- **aggressive**: Lenient screening, highest risk tolerance\n\nNote: Changing the risk profile will affect future compliance screenings but will not retroactively change past screenings.", "operationId": "organizations_updateRiskProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRiskProfileRequest" } } } }, "responses": { "200": { "description": "Risk profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRiskProfileResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update organization risk profile", "tags": ["Organizations"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "get": { "description": "Retrieve the current compliance risk profile for the authenticated user's organization.", "operationId": "organizations_getRiskProfile", "parameters": [], "responses": { "200": { "description": "Risk profile retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskProfileResponse" } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get organization risk profile", "tags": ["Organizations"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/organizations/secrets": { "post": { "description": "Store a secret (e.g., API key) securely in the vault for the authenticated user's organization.\n\nSecrets are stored at the organization level and shared across all workspaces within the organization.\n\nCurrently supported providers:\n- **CIRCLE_MINT**: Circle Mint API key for payment processing\n- **OPENFX**: OpenFX credentials bundle (orgId, apiKey, privateKey, webhookSecret)\n- **CIRCLE_PAYMENTS_NETWORK**: Circle Payments Network (CPN) API key, validated by creating a CPN webhook subscription\n\nThe secret is encrypted and stored in Basis Theory vault. Only a masked version is returned.", "operationId": "organizations_createSecret", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" } } } }, "responses": { "200": { "description": "Secret stored successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create or update an organization secret", "tags": ["Organizations"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments": { "get": { "description": "Retrieve all payments for the authenticated user's organization.", "operationId": "payments_getPayments", "parameters": [ { "name": "start_date", "required": false, "in": "query", "description": "Start date for filtering payments (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "end_date", "required": false, "in": "query", "description": "End date for filtering payments (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "direction", "required": false, "in": "query", "description": "Payment direction filter: 'outbound' for outgoing payments, 'inbound' for incoming payments", "schema": { "type": "string", "enum": ["outbound", "inbound"] } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination (1-based)" }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items per page (default: 20)" } ], "responses": { "200": { "description": "Successfully retrieved team payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaymentsResponse" }, "example": { "data": [ { "id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "risk_status": "automatically_approved", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T09:59:00.000Z", "steps": [ { "id": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "payment_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get payments", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "post": { "description": "Create a payment. Returns the created payment details.", "operationId": "payments_createPayment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "examples": { "default": { "summary": "Create a standard payment", "value": { "organization_reference_id": "ref_123", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "currency": "USDC", "network": "ETHEREUM" } } } } } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "9f3b7e1c-4a2d-4f69-b5a8-0c6e2d9f1a3b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "risk_status": "unchecked", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "unreserved", "balance_reserved_at": null, "steps": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create payment", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/internal": { "get": { "description": "Retrieve payments optimized for table display. Returns only fields needed for the payments table UI.", "operationId": "payments_getPaymentsInternal", "parameters": [ { "name": "start_date", "required": false, "in": "query", "description": "Start date for filtering payments (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "end_date", "required": false, "in": "query", "description": "End date for filtering payments (ISO 8601 format)", "schema": { "type": "string" } }, { "name": "direction", "required": false, "in": "query", "description": "Payment direction filter: 'outbound' for outgoing payments, 'inbound' for incoming payments", "schema": { "type": "string", "enum": ["outbound", "inbound"] } }, { "name": "status", "required": false, "in": "query", "description": "Payment status for filtering payments", "schema": { "type": "string", "enum": [ "queued", "processing", "ready-to-submit", "rejected", "sent", "need-review", "compliance-blocked", "insufficient-balance" ] } }, { "name": "payment_type", "required": false, "in": "query", "description": "Payment type filter: 'deposit', 'withdrawal', or 'transfer'", "schema": { "type": "string", "enum": ["deposit", "withdrawal", "transfer"] } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination (1-based)" }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items per page (default: 20)" } ], "responses": { "200": { "description": "Successfully retrieved team payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalPaymentListResponse" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "[INTERNAL] Get payments for UI table", "tags": ["Payments"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/internal/{paymentId}": { "get": { "description": "Retrieve a single payment with full details including steps and entity data for UI display.", "operationId": "payments_getPaymentInternal", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "description": "Unique identifier of the payment to retrieve", "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "[INTERNAL] Get single payment for UI", "tags": ["Payments"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/simulate-inbound": { "post": { "description": "Sends a real on-chain test-USDC transfer from the platform faucet into a managed wallet and forces the risk-screening verdict to mocked_risk_status. Only available in staging. Returns 201 with the screened payment, or 202 with the tx hash if it is still being detected/screened.", "operationId": "payments_simulateInbound", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateInboundPaymentRequest" } } } }, "responses": { "201": { "description": "The simulated inbound payment, already screened to mocked_risk_status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "202": { "description": "The on-chain transfer was broadcast but the inbound was not detected and screened within the wait budget. Once payment_id is present, poll GET /v1/payments/{paymentId} for the screened payment.", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": [ "tx_hash", "network", "status", "payment_id" ], "properties": { "tx_hash": { "type": "string" }, "network": { "type": "string" }, "status": { "type": "string", "enum": ["pending"], "example": "pending" }, "payment_id": { "type": "string", "format": "uuid", "nullable": true } } } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Simulate an inbound payment with a chosen risk status (staging)", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/{paymentId}": { "get": { "description": "Retrieve a specific payment by ID.", "operationId": "payments_getPaymentById", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "description": "Unique identifier of the payment to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "risk_status": "automatically_approved", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T09:59:00.000Z", "steps": [ { "id": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "payment_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get payment by ID", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "patch": { "description": "Update a payment with accounts.", "operationId": "payments_updatePayment", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "description": "Unique identifier of the payment to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentRequest" }, "examples": { "default": { "summary": "Update payment accounts", "value": { "organization_reference_id": "ref_456", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889" } } } } } } } }, "responses": { "200": { "description": "Payment updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_456", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "risk_status": "automatically_approved", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T09:59:00.000Z", "steps": [ { "id": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "payment_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-05T09:00:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update payment", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/{paymentId}/review": { "post": { "description": "Manually review and approve or reject a payment requiring risk review.", "operationId": "payments_reviewPayment", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "description": "Unique identifier of the payment to review", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewPaymentRequest" }, "examples": { "default": { "summary": "Approve payment", "value": { "is_approved": true } } } } } }, "responses": { "200": { "description": "Payment review completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "risk_status": "manually_approved", "risk_status_reasons": [ { "risk_status_reason_type": "ownership", "risk_status_reason_category": "Malware", "risk_status_reason_message": "Address linked to known malware family", "risk_status_reason_severity": "high" } ], "risk_reviewed_by": "9c3e7f5a-2b1d-4f48-a6e0-8c4b2d1f9a3e", "risk_reviewed_at": "2024-03-01T10:30:00.000Z", "balance_status": "reserved", "balance_reserved_at": "2024-03-01T09:59:00.000Z", "steps": [ { "id": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "payment_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:35:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Submit risk review", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/payments/{paymentId}/steps/{stepId}/sign": { "post": { "description": "Submit a signature for a self-custodial payment step. Webhook updates will be sent as the signature is validated and submitted onchain.", "operationId": "payments_signPaymentStep", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "description": "Unique identifier of the payment", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } }, { "name": "stepId", "required": true, "in": "path", "description": "Unique identifier of the payment step to sign", "schema": { "format": "uuid", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignPaymentStepRequest" }, "examples": { "default": { "summary": "Sign a payment step", "value": { "signature": "" } } } } } }, "responses": { "200": { "description": "Signed transaction broadcast on-chain. The step is `confirmed` with its broadcast `transaction_hash`; block finality (`completed`) follows asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "ETHEREUM" } }, "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "risk_status": "automatically_approved", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T09:59:00.000Z", "steps": [ { "id": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a", "payment_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" }, "to": { "account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "amount": "10.00", "currency": "USDC", "network": "ETHEREUM" } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "turnkey", "status": "confirmed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Sign payment step", "tags": ["Payments"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/activity": { "get": { "operationId": "treasury_getTreasuryActivity", "parameters": [ { "name": "page", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "account_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "completed_only", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "types", "required": false, "in": "query", "description": "Filter by activity type", "schema": { "enum": ["deposit", "withdrawal", "rebalance"], "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get treasury activity feed (deposits, withdrawals + rebalances)", "tags": ["Treasury"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/balances": { "get": { "description": "Get treasury balances grouped by currency. Each currency includes: available balance from managed accounts, pending review payment amounts, and rejected payment amounts. Optionally filter by specific currencies.", "operationId": "treasury_getTreasuryBalances", "parameters": [ { "name": "currency", "required": false, "in": "query", "description": "Filter by currency. Comma-separated for multiple values. Example: USDC,USDT", "schema": { "example": "USDC", "type": "string" } }, { "name": "managed", "required": false, "in": "query", "description": "Filter by managed status. 'true' for managed accounts only, 'false' for non-managed only, omit for all accounts.", "schema": { "example": "true", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryBalancesResponseDto" } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get treasury balances", "tags": ["Treasury"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/deposits": { "get": { "description": "Retrieve a paginated list of all deposits for the workspace.", "operationId": "treasury_getDeposits", "parameters": [ { "name": "ids", "required": false, "in": "query", "description": "Filter by deposit IDs (comma-separated UUIDs)", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "to_account_id", "required": false, "in": "query", "description": "Filter by destination account ID (desired.to.account_id).", "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-based)", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page (default: 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Deposits retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDepositsResponse" }, "example": { "data": [ { "id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "inbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "treasury-3134", "error_message": "Currency pair MXN → ETH is not supported for OpenFX deposits" }, { "error_code": "treasury-3135", "error_message": "Source bank currency 'USD' does not match deposit from_currency" }, { "error_code": "treasury-3136", "error_message": "Failed to obtain OpenFX quote for MXN → USDC" }, { "error_code": "treasury-3331", "error_message": "Amount 16 USD is below the provider's minimum tradable amount of 100 USD" }, { "error_code": "treasury-3332", "error_message": "Amount 30000000 USD is above the provider's maximum tradable amount of 25000000 USD" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get deposits", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "post": { "description": "Create a deposit payment and get deposit instructions.", "operationId": "treasury_createDeposit", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositRequest" }, "examples": { "default": { "summary": "Create deposit", "value": { "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD" }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "currency": "USDC" } } } } } } } }, "responses": { "201": { "description": "Deposit created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositResponse" }, "example": { "data": { "id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "inbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "steps": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "treasury-3134", "error_message": "Currency pair MXN → ETH is not supported for OpenFX deposits" }, { "error_code": "treasury-3135", "error_message": "Source bank currency 'USD' does not match deposit from_currency" }, { "error_code": "treasury-3136", "error_message": "Failed to obtain OpenFX quote for MXN → USDC" }, { "error_code": "treasury-3331", "error_message": "Amount 16 USD is below the provider's minimum tradable amount of 100 USD" }, { "error_code": "treasury-3332", "error_message": "Amount 30000000 USD is above the provider's maximum tradable amount of 25000000 USD" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create deposit", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/deposits/{id}": { "get": { "description": "Retrieve a deposit payment by its unique identifier.", "operationId": "treasury_getDeposit", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deposit ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositResponse" }, "examples": { "circle": { "summary": "Circle provider deposit", "value": { "data": { "id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "inbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get deposit by ID", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/deposits/{id}/instructions": { "get": { "description": "Get deposit instructions for an existing deposit.\n\n", "operationId": "treasury_getDepositInstructions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deposit ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit instructions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositInstructionsResponse" }, "example": { "data": { "from_account": { "id": "55042f8f-e527-56f1-b57c-eef23ca862db", "name": "Acme Corp Operating Account", "bank_name": "Chase Bank", "bank_account_number": "845748459212", "bank_code_type": "ROUTING", "bank_identifier_code": "021000021", "bank_swift_code": "CHASUS33XXX" }, "to_account": { "id": "7a4c2d8e-1b5f-4e69-a7d1-3f8e5c2b9a0d", "name": "Circle USD Wire Deposit Account", "bank_name": "STANDARD CHARTERED BANK", "bank_account_number": "11001259978", "bank_code_type": "ROUTING", "bank_identifier_code": "322286803", "bank_swift_code": "SCBLSG22XXX", "tracking_reference": "CIR24K2SK3", "belongs_to": { "business_legal_name": "CIRCLE INTERNET FINANCIAL INC", "business_street_address1": "99 HIGH STREET", "business_street_address2": "LEVEL 17 SUITE 1701", "business_city": "BOSTON", "business_state": "MA", "business_postal_code": "02110", "business_country": "US" } }, "amount": "1000", "currency": "USD" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get deposit instructions by id", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/deposits/{id}/simulate": { "post": { "description": "Simulate a wire deposit by triggering Circle's mock wire API. Only available in sandbox environments.", "operationId": "treasury_simulateDeposit", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Deposit ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Deposit simulation triggered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositResponse" }, "example": { "data": { "id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "inbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USDC", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "deposit_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "a81bc1f4-7e3d-4926-b04f-3d2e8a9c5f17", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USDC", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Simulate deposit in sandbox", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/rebalances": { "get": { "description": "Retrieve a paginated list of all rebalances for the workspace.", "operationId": "treasury_getRebalances", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination (1-based)" }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items per page (default: 20)" } ], "responses": { "200": { "description": "Rebalances retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRebalancesResponse" }, "example": { "data": [ { "id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "rebalance", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "BASE" } }, "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "7d3e1a9f-2c4b-4f85-b0a6-8e5c2d1f3b9a", "rebalance_id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get rebalances", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "post": { "description": "Create an internal rebalance between managed accounts.\n\n**Validation rules:**\n- `desired.from.network` / `desired.to.network` are required for wallet accounts and disallowed for ledger accounts.", "operationId": "treasury_createRebalance", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRebalanceRequest" }, "examples": { "default": { "summary": "Same currency/network rebalance", "value": { "organization_reference_id": "ref_123", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "currency": "USDC", "network": "BASE" } } } } } } } }, "responses": { "201": { "description": "Rebalance created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebalanceResponse" }, "example": { "data": { "id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "rebalance", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "BASE" } }, "estimated": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "unreserved", "balance_reserved_at": null, "steps": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create rebalance", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/rebalances/{id}": { "get": { "description": "Retrieve a rebalance by its unique identifier.", "operationId": "treasury_getRebalance", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Rebalance ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rebalance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebalanceResponse" }, "example": { "data": { "id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "rebalance", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "BASE" } }, "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "7d3e1a9f-2c4b-4f85-b0a6-8e5c2d1f3b9a", "rebalance_id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "completed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": "2024-03-01T10:02:30.000Z", "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:30.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get rebalance by ID", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/rebalances/{id}/steps/{stepId}/sign": { "post": { "description": "Submit a signature for a self-custodial wallet-to-wallet rebalance step. Webhook updates will be sent as the signature is validated and submitted onchain.", "operationId": "treasury_signRebalanceStep", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Rebalance ID", "schema": { "type": "string" } }, { "name": "stepId", "required": true, "in": "path", "description": "Rebalance step ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRebalanceStepRequest" } } } }, "responses": { "200": { "description": "Signed transaction broadcast on-chain. The step is `confirmed` with its broadcast `transaction_hash`; block finality follows asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebalanceResponse" }, "example": { "data": { "id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "rebalance", "desired": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": null, "currency": "USDC", "network": "BASE" } }, "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "7d3e1a9f-2c4b-4f85-b0a6-8e5c2d1f3b9a", "rebalance_id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "turnkey", "status": "confirmed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "expires_at": "2024-03-04T10:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } }, "example": { "errors": [ { "error_code": "treasury-3013", "error_message": "Rebalance step is not in a signable state" }, { "error_code": "treasury-3016", "error_message": "Signed transaction does not match the rebalance details" } ] } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Sign rebalance step", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/withdrawals": { "get": { "description": "Retrieve a paginated list of all withdrawals for the workspace.", "operationId": "treasury_getWithdrawals", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination (1-based)" }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items per page (default: 20)" } ], "responses": { "200": { "description": "Withdrawals retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWithdrawalsResponse" }, "example": { "data": [ { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USD", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 2, "step_type": "transfer", "estimated": { "from": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get withdrawals", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } }, "post": { "description": "Create a withdrawal from a managed account or self-custodial wallet to an external bank account.\n\n**Source types:**\n- Circle USDC ledger (path A) — `desired.from.network` omitted.\n- Self-custodial wallet (path B) — `desired.from.network` populated (e.g., `BASE`).", "operationId": "treasury_createWithdrawal", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalRequest" }, "examples": { "default": { "summary": "Withdraw USDC from Circle ledger to USD bank account", "value": { "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC" }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "currency": "USD" } } } } } } } }, "responses": { "201": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" }, "example": { "data": { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USD", "network": null } }, "estimated": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "unreserved", "balance_reserved_at": null, "steps": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create withdrawal", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/withdrawals/{id}": { "get": { "description": "Retrieve a withdrawal by its unique identifier.", "operationId": "treasury_getWithdrawal", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Withdrawal ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawal retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" }, "example": { "data": { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USD", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 2, "step_type": "transfer", "estimated": { "from": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USD", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0001", "error_message": "Resource not found" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get withdrawal by ID", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/treasury/withdrawals/{id}/steps/{stepId}/sign": { "post": { "description": "Submit a signature for a self-custodial wallet-source withdrawal step. Webhook updates will be sent as the signature is validated and submitted onchain.", "operationId": "treasury_signWithdrawalStep", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Withdrawal ID", "schema": { "type": "string" } }, { "name": "stepId", "required": true, "in": "path", "description": "Withdrawal step ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignWithdrawalStepRequest" } } } }, "responses": { "200": { "description": "Signed transaction broadcast on-chain. The wallet step (`step_sequence` 1) is `confirmed` with its broadcast `transaction_hash`; block finality and the payout step (`step_sequence` 2) follow asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResponse" }, "example": { "data": { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "desired": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": null, "currency": "USD", "network": null } }, "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 1, "step_type": "transfer", "estimated": { "from": { "account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "amount": "1000", "currency": "USDC", "network": "BASE" }, "to": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USDC", "network": "BASE" } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": "0xabc123", "unsigned_transaction": null, "fees": [], "provider_key": "turnkey", "status": "confirmed", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": "2024-03-01T10:02:00.000Z", "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "withdrawal_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 2, "step_type": "transfer", "estimated": { "from": { "account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "amount": "1000", "currency": "USDC", "network": null }, "to": { "account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "amount": "1000", "currency": "USD", "network": null } }, "actual": { "from": { "account_id": null, "amount": null, "currency": null, "network": null }, "to": { "account_id": null, "amount": null, "currency": null, "network": null } }, "transaction_hash": null, "unsigned_transaction": null, "fees": [], "provider_key": "circle_mint", "status": "created", "status_reasons": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:00.000Z", "submitted_at": null, "confirmed_at": null, "completed_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:02:00.000Z", "expires_at": "2024-03-01T14:00:00.000Z" } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } }, "example": { "errors": [ { "error_code": "treasury-3306", "error_message": "Withdrawal step is not in a signable state" }, { "error_code": "treasury-3309", "error_message": "Signed transaction does not match the withdrawal details" } ] } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "404": { "description": "The withdrawal does not exist in this workspace (`treasury-1200`), or the referenced step does not exist on it (`treasury-1203`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } }, "example": { "errors": [ { "error_code": "treasury-1200", "error_message": "Withdrawal with id 'wd_123' not found" }, { "error_code": "treasury-1203", "error_message": "Transfer step not found for withdrawal with id 'wd_123'" } ] } } } }, "409": { "description": "Source wallet's live on-chain balance is below the withdrawal amount at sign time. Retry once the wallet is funded; `withdrawal.balance_updated` fires with `balance_status` `awaiting_funds`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } }, "example": { "errors": [ { "error_code": "treasury-3319", "error_message": "Source wallet has insufficient on-chain balance to sign" } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0006", "error_message": "An unexpected error occurred" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Sign withdrawal step", "tags": ["Treasury"], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/users/me": { "get": { "description": "Retrieve the authenticated user's profile information including user details and team/organization information.", "operationId": "users_getCurrentUser", "parameters": [], "responses": { "200": { "description": "Successfully retrieved user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponseDto" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get current user profile", "tags": ["Users"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/users/signup": { "post": { "operationId": "users_signup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponseDto" } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } }, "403": { "description": "Access denied - insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0003", "error_message": "You do not have permission to access this resource" } ] } } } } } }, "summary": "Sign up a new user and create a team", "tags": ["Users"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "forward-user-info-inbound" ] } } } }, "/v1/webhooks/circle": { "post": { "operationId": "webhook_receiveCircleWebhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } }, "summary": "Receive webhook notifications from Circle", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "webhook_receiveCircleWebhook_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/webhooks/circle/{organizationId}": { "post": { "operationId": "webhook_receiveCircleWebhookForOrg", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } }, "summary": "Receive webhook notifications from Circle for a specific organization", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "webhook_receiveCircleWebhookForOrg_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/webhooks/cpn/{organizationId}": { "post": { "operationId": "webhook_receiveCpnWebhook", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID the CPN subscription was registered for", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } }, { "name": "x-circle-signature", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-circle-key-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "bypass-sig-verification", "required": false, "in": "header", "description": "Development-only flag to skip signature verification.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "400": { "description": "Invalid organizationId", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Invalid webhook signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "webhooks-0004", "error_message": "Invalid webhook signature" } ] } } } } } }, "summary": "Receive CPN (Circle Payments Network) webhook notifications for an organization", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "webhook_receiveCpnWebhook_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID the CPN subscription was registered for", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } }, { "name": "x-circle-signature", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-circle-key-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "bypass-sig-verification", "required": false, "in": "header", "description": "Development-only flag to skip signature verification.", "schema": { "type": "string" } } ], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/webhooks/notabene": { "post": { "operationId": "notabeneWebhook_receive", "parameters": [ { "name": "svix-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-timestamp", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "401": { "description": "Invalid webhook signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "webhooks-0004", "error_message": "Invalid webhook signature" } ] } } } } } }, "summary": "Receive Notabene Travel Rule webhook notifications", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "notabeneWebhook_receive_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [ { "name": "svix-id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-timestamp", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "svix-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/webhooks/openfx/{workspaceId}": { "post": { "operationId": "webhook_receiveOpenFxWebhook", "parameters": [ { "name": "workspaceId", "required": true, "in": "path", "description": "Workspace ID receiving the OpenFX webhook", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } }, { "name": "x-openfx-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "400": { "description": "Invalid workspaceId or webhook payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "counterparties-3001", "error_message": "classification must be one of: individual, business" }, { "error_code": "counterparties-3002", "error_message": "business_legal_name is required when classification is business" } ] } } } } }, "401": { "description": "Invalid webhook signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "api-0004", "error_message": "Unauthorized" } ] } } } } } }, "summary": "Receive workspace-scoped OpenFX webhook notifications", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "webhook_receiveOpenFxWebhook_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [ { "name": "workspaceId", "required": true, "in": "path", "description": "Workspace ID receiving the OpenFX webhook", "schema": { "format": "uuid", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "type": "string" } }, { "name": "x-openfx-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/webhooks/quicknode/{network}": { "post": { "operationId": "webhook_receiveQuicknodeWebhookForNetwork", "parameters": [ { "name": "network", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-qn-signature", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-qn-nonce", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-qn-timestamp", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "bypass-sig-verification", "required": false, "in": "header", "description": "Development-only flag to skip signature verification.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuicknodeWebhookPayloadDto" } } } }, "responses": { "200": { "description": "Webhook processed successfully" }, "400": { "description": "Invalid webhook payload" }, "401": { "description": "Invalid webhook signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": ["error_code", "error_message"] } } }, "required": ["errors"], "example": { "errors": [ { "error_code": "webhooks-0004", "error_message": "Invalid webhook signature" } ] } } } } } }, "summary": "Receive webhook updates from Quicknode", "tags": ["webhooks"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } }, "security": [] }, "head": { "operationId": "webhook_receiveQuicknodeWebhookForNetwork_head", "summary": "Webhook endpoint reachability probe", "tags": ["webhooks"], "parameters": [ { "name": "network", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-qn-signature", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-qn-nonce", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "x-qn-timestamp", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "bypass-sig-verification", "required": false, "in": "header", "description": "Development-only flag to skip signature verification.", "schema": { "type": "string" } } ], "x-internal": true, "security": [], "responses": { "200": { "description": "Endpoint reachable" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "forwardToBackend", "module": "$import(./modules/forward-to-backend)" }, "policies": { "inbound": ["set-backend-secret-inbound"] } } } }, "/v1/mcp": { "post": { "operationId": "mcp_server", "summary": "MCP Server", "description": "Model Context Protocol endpoint for AI agent tool discovery and invocation", "tags": ["MCP"], "x-internal": true, "responses": { "200": { "description": "MCP JSON-RPC response" } }, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mcpServerHandler", "module": "$import(@zuplo/runtime)", "options": { "name": "tesser-payments", "version": "1.0.0", "operations": [ { "file": "./config/routes.oas.json", "id": "account_findAll" }, { "file": "./config/routes.oas.json", "id": "account_createBankAccount" }, { "file": "./config/routes.oas.json", "id": "account_createLedgerAccount" }, { "file": "./config/routes.oas.json", "id": "account_createWalletAccount" }, { "file": "./config/routes.oas.json", "id": "account_findOne" }, { "file": "./config/routes.oas.json", "id": "account_update" }, { "file": "./config/routes.oas.json", "id": "currency_getCurrencies" }, { "file": "./config/routes.oas.json", "id": "counterparty_findAll" }, { "file": "./config/routes.oas.json", "id": "counterparty_create" }, { "file": "./config/routes.oas.json", "id": "counterparty_findOne" }, { "file": "./config/routes.oas.json", "id": "tenant_findAll" }, { "file": "./config/routes.oas.json", "id": "tenant_create" }, { "file": "./config/routes.oas.json", "id": "tenant_findOne" }, { "file": "./config/routes.oas.json", "id": "networks_getNetworks" }, { "file": "./config/routes.oas.json", "id": "payments_getPayments" }, { "file": "./config/routes.oas.json", "id": "payments_createPayment" }, { "file": "./config/routes.oas.json", "id": "payments_simulateInbound" }, { "file": "./config/routes.oas.json", "id": "payments_getPaymentById" }, { "file": "./config/routes.oas.json", "id": "payments_updatePayment" }, { "file": "./config/routes.oas.json", "id": "payments_reviewPayment" }, { "file": "./config/routes.oas.json", "id": "payments_signPaymentStep" }, { "file": "./config/routes.oas.json", "id": "treasury_getDeposits" }, { "file": "./config/routes.oas.json", "id": "treasury_createDeposit" }, { "file": "./config/routes.oas.json", "id": "treasury_getDeposit" }, { "file": "./config/routes.oas.json", "id": "treasury_getDepositInstructions" }, { "file": "./config/routes.oas.json", "id": "treasury_simulateDeposit" }, { "file": "./config/routes.oas.json", "id": "treasury_getRebalances" }, { "file": "./config/routes.oas.json", "id": "treasury_createRebalance" }, { "file": "./config/routes.oas.json", "id": "treasury_getRebalance" }, { "file": "./config/routes.oas.json", "id": "treasury_signRebalanceStep" }, { "file": "./config/routes.oas.json", "id": "treasury_getWithdrawals" }, { "file": "./config/routes.oas.json", "id": "treasury_createWithdrawal" }, { "file": "./config/routes.oas.json", "id": "treasury_getWithdrawal" }, { "file": "./config/routes.oas.json", "id": "treasury_signWithdrawalStep" } ] } }, "policies": { "inbound": [ "set-backend-secret-inbound", "auth0-jwt-auth-inbound", "detect-auth-type-inbound" ] } } } }, "/": { "get": { "operationId": "root_healthCheck", "summary": "Root health check", "tags": ["health"], "x-internal": true, "responses": { "200": { "description": "OK" } }, "security": [], "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "rootHealthCheck", "module": "$import(./modules/health-check)" }, "policies": { "inbound": [] } } } } }, "info": { "title": "Tesser API", "description": "The Tesser Payments Platform API documentation.", "version": "v1", "contact": {} }, "tags": [ { "name": "users", "description": "" }, { "name": "teams", "description": "" }, { "name": "payments", "description": "" }, { "name": "entities", "description": "" } ], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Enter your JWT token.\n\nTo obtain a token, make a request to Auth0:\n\n```bash\ncurl --request POST \\\n --url https://dev-awqy75wdabpsnsvu.us.auth0.com/oauth/token \\\n --header 'content-type: application/json' \\\n --data '{\n \"client_id\":\"YOUR_CLIENT_ID\",\n \"client_secret\":\"YOUR_CLIENT_SECRET\",\n \"audience\":\"https://sandbox.tesserx.co\",\n \"grant_type\":\"client_credentials\"\n }'\n```\n\nThe response will contain an `access_token` field which should be used as the Bearer token." } }, "schemas": { "BankAccountData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the account" }, "workspace_id": { "type": "string", "description": "Workspace ID the account belongs to" }, "tenant_id": { "type": "string", "nullable": true, "description": "Tenant ID (if account belongs to a tenant)" }, "counterparty_id": { "type": "string", "nullable": true, "description": "Counterparty ID (if account belongs to a counterparty)" }, "type": { "type": "string", "description": "Account type" }, "name": { "type": "string", "description": "Account name" }, "created_at": { "type": "string", "description": "Creation timestamp" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "bank_name": { "type": "string", "description": "Name of the financial institution" }, "bank_code_type": { "type": "string", "description": "Type of bank code (e.g., SWIFT, BIC, IBAN, ROUTING, SORT_CODE)" }, "bank_identifier_code": { "type": "string", "description": "Bank identifier code value" }, "bank_swift_code": { "type": "string", "nullable": true, "description": "SWIFT code" }, "bank_account_number": { "type": "string", "nullable": true, "description": "Bank account number (masked, only with include_secure=true)" } }, "required": [ "id", "workspace_id", "type", "name", "created_at", "updated_at", "bank_name", "bank_code_type", "bank_identifier_code" ] }, "CreateBankAccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BankAccountData" } }, "required": ["data"] }, "LedgerAssetDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol", "example": "USDC" }, "available_balance": { "type": "string", "description": "Available balance in smallest unit", "example": "1000000" } }, "required": ["currency", "available_balance"] }, "LedgerAccountData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the account" }, "workspace_id": { "type": "string", "description": "Workspace ID the account belongs to" }, "tenant_id": { "type": "string", "nullable": true, "description": "Tenant ID (if account belongs to a tenant)" }, "counterparty_id": { "type": "string", "nullable": true, "description": "Counterparty ID (if account belongs to a counterparty)" }, "type": { "type": "string", "description": "Account type" }, "name": { "type": "string", "description": "Account name" }, "created_at": { "type": "string", "description": "Creation timestamp" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "provider": { "type": "string", "description": "Liquidity provider that manages this ledger account", "enum": ["CIRCLE_MINT", "KRAKEN", "OPENFX"] }, "assets": { "description": "Ledger assets with balances", "type": "array", "items": { "$ref": "#/components/schemas/LedgerAssetDto" } } }, "required": [ "id", "workspace_id", "type", "name", "created_at", "updated_at", "provider" ] }, "CreateLedgerAccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LedgerAccountData" } }, "required": ["data"] }, "WalletAssetDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol", "example": "USDC" }, "network": { "type": "string", "description": "Blockchain network", "example": "POLYGON" }, "available_balance": { "type": "string", "description": "Available balance in smallest unit", "example": "1000000" } }, "required": ["currency", "network", "available_balance"] }, "WalletAccountData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the account" }, "workspace_id": { "type": "string", "description": "Workspace ID the account belongs to" }, "tenant_id": { "type": "string", "nullable": true, "description": "Tenant ID (if account belongs to a tenant)" }, "counterparty_id": { "type": "string", "nullable": true, "description": "Counterparty ID (if account belongs to a counterparty)" }, "type": { "type": "string", "description": "Account type" }, "name": { "type": "string", "description": "Account name" }, "created_at": { "type": "string", "description": "Creation timestamp" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "crypto_wallet_address": { "type": "string", "description": "Blockchain wallet address" }, "is_managed": { "type": "boolean", "description": "Whether this is a managed wallet (provisioned by Tesser), or unmanaged (not provisioned by Tesser)" }, "assets": { "description": "Wallet assets with balances", "type": "array", "items": { "$ref": "#/components/schemas/WalletAssetDto" } } }, "required": [ "id", "workspace_id", "type", "name", "created_at", "updated_at", "crypto_wallet_address", "is_managed" ] }, "CreateWalletAccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletAccountData" } }, "required": ["data"] }, "AccountAssetDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol", "example": "USDC" }, "network": { "type": "string", "description": "Blockchain network (only for wallet accounts)", "example": "POLYGON" }, "available_balance": { "type": "string", "description": "Available balance in smallest unit", "example": "1000000" } }, "required": ["currency", "available_balance"] }, "AccountData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the account" }, "workspace_id": { "type": "string", "description": "Workspace ID the account belongs to" }, "tenant_id": { "type": "string", "nullable": true, "description": "Tenant ID (if account belongs to a tenant)" }, "counterparty_id": { "type": "string", "nullable": true, "description": "Counterparty ID (if account belongs to a counterparty)" }, "type": { "type": "string", "description": "Account type" }, "name": { "type": "string", "description": "Account name" }, "bank_name": { "type": "string", "nullable": true, "description": "Bank name (only for fiat_bank accounts)" }, "bank_code_type": { "type": "string", "nullable": true, "description": "Bank code type (only for fiat_bank accounts)" }, "bank_identifier_code": { "type": "string", "nullable": true, "description": "Bank identifier code (only for fiat_bank accounts)" }, "bank_swift_code": { "type": "string", "nullable": true, "description": "SWIFT code (only for fiat_bank accounts)" }, "bank_account_number": { "type": "string", "nullable": true, "description": "Bank account number (masked, only with include_secure=true)" }, "crypto_wallet_address": { "type": "string", "nullable": true, "description": "Crypto wallet address (only for wallet accounts)" }, "is_managed": { "type": "boolean", "nullable": true, "description": "Is managed wallet (only for wallet accounts)" }, "provider": { "type": "string", "nullable": true, "description": "Ledger provider (only for ledger accounts)", "enum": ["CIRCLE_MINT", "KRAKEN", "OPENFX"] }, "assets": { "description": "Account assets with balances (for wallet and ledger accounts)", "type": "array", "items": { "$ref": "#/components/schemas/AccountAssetDto" } }, "created_at": { "type": "string", "description": "Creation timestamp" }, "updated_at": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "workspace_id", "type", "name", "created_at", "updated_at" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number." }, "limit": { "type": "number", "description": "Number of items per page." }, "total": { "type": "number", "description": "Total number of items." }, "total_pages": { "type": "number", "description": "Total number of pages." }, "has_next": { "type": "boolean", "description": "Whether there is a next page." }, "has_prev": { "type": "boolean", "description": "Whether there is a previous page." } }, "required": [ "page", "limit", "total", "total_pages", "has_next", "has_prev" ] }, "AccountListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountData" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "AccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountData" } }, "required": ["data"] }, "UpdateAccountResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountData" } }, "required": ["data"] }, "CreateBankAccountRequestDto": { "type": "object", "properties": { "tenant_id": { "description": "Tenant ID (mutually exclusive with counterparty_id). Links this account to a specific tenant.", "example": "550e8400-e29b-41d4-a716-446655440002", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "counterparty_id": { "description": "Counterparty ID (mutually exclusive with tenant_id). Links this account to a specific counterparty.", "example": "660e8400-e29b-41d4-a716-446655440003", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the bank account", "example": "Operating Account - EU", "maxLength": 255 }, "bank_name": { "type": "string", "minLength": 1, "description": "Name of the financial institution", "example": "Chase Bank", "maxLength": 255 }, "bank_code_type": { "type": "string", "minLength": 1, "description": "Type of bank code (e.g., SWIFT, BIC, IBAN, ROUTING, SORT_CODE)", "example": "SWIFT", "maxLength": 50 }, "bank_identifier_code": { "type": "string", "minLength": 1, "description": "Bank identifier code value", "example": "CHASUS33", "maxLength": 255 }, "bank_swift_code": { "description": "SWIFT code", "example": "CHASUS33XXX", "type": "string", "minLength": 1, "nullable": true }, "bank_account_number": { "type": "string", "minLength": 1, "description": "Bank account number. SECURE FIELD: Encrypted and stored in vault, never returned in responses. Required in API request.", "example": "1234567890", "maxLength": 255 } }, "required": [ "name", "bank_name", "bank_code_type", "bank_identifier_code", "bank_account_number" ] }, "CreateWalletAccountRequestDto": { "type": "object", "properties": { "tenant_id": { "description": "Tenant ID (mutually exclusive with counterparty_id). Links this wallet to a specific tenant.", "example": "550e8400-e29b-41d4-a716-446655440002", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "counterparty_id": { "description": "Counterparty ID (mutually exclusive with tenant_id). Links this wallet to a specific counterparty.", "example": "660e8400-e29b-41d4-a716-446655440003", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the wallet account", "example": "Treasury Wallet - Ethereum", "maxLength": 255 }, "type": { "type": "string", "enum": [ "stablecoin_ethereum", "stablecoin_solana", "stablecoin_stellar" ], "description": "Stablecoin network type. Determines which blockchain network the wallet operates on.", "example": "stablecoin_ethereum" }, "signature": { "type": "string", "description": "A cryptographic stamp used to verify the integrity and authenticity of the request. This ensures the request was signed by an authorized key. Required for managed wallets (is_managed=true). See Documentation > Signing for more details.", "example": "eyJwdWJsaWNLZXkiOiJwdWJfZXhhbXBsZSIsInNpZ25hdHVyZSI6InNpZ19leGFtcGxlIiwic2NoZW1lIjoiRUQyNTUxOSJ9" }, "is_managed": { "default": false, "type": "boolean", "description": "Whether this is a managed wallet (provisioned by Tesser), or unmanaged (not provisioned by Tesser). Managed wallets (true) require a signature and automatically create USDC/USDT assets. Unmanaged wallets (false) require a wallet_address. Defaults to false.", "example": false }, "wallet_address": { "type": "string", "description": "Blockchain wallet address. Required for unmanaged wallets (is_managed=false). Auto-generated for managed wallets.", "example": "0x742d35CC6634C0532925a3B844BC9e7595f8fe0B" } }, "required": ["name", "type"] }, "CreateLedgerAccountRequestDto": { "type": "object", "properties": { "tenant_id": { "description": "Tenant ID (mutually exclusive with counterparty_id). Links this ledger account to a specific tenant.", "example": "550e8400-e29b-41d4-a716-446655440002", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "counterparty_id": { "description": "Counterparty ID (mutually exclusive with tenant_id). Links this ledger account to a specific counterparty.", "example": "660e8400-e29b-41d4-a716-446655440003", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the ledger account", "example": "Circle USDC Account", "maxLength": 255 }, "provider": { "type": "string", "enum": ["CIRCLE_MINT", "KRAKEN", "OPENFX"], "description": "Liquidity provider that manages this ledger account. CIRCLE_MINT for Circle Mint accounts, KRAKEN for Kraken exchange accounts.", "example": "CIRCLE_MINT" } }, "required": ["name", "provider"] }, "UpdateAccountRequestDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New account name" } } }, "CreateInvitationRequestDto": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": ["email"] }, "Currency": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the currency (e.g., 'Circle USD')" }, "key": { "type": "string", "description": "Currency code/key (e.g., 'USDC', 'USD')" }, "decimals": { "type": "number", "description": "Number of decimal places for the currency" }, "network": { "description": "Blockchain network (e.g., 'POLYGON') or null for fiat currencies. See GET /networks for supported values.", "type": "string", "nullable": true } }, "required": ["name", "key", "decimals", "network"] }, "CurrenciesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the currency (e.g., 'Circle USD')" }, "key": { "type": "string", "description": "Currency code/key (e.g., 'USDC', 'USD')" }, "decimals": { "type": "number", "description": "Number of decimal places for the currency" }, "network": { "description": "Blockchain network (e.g., 'POLYGON') or null for fiat currencies. See GET /networks for supported values.", "type": "string", "nullable": true } }, "required": ["name", "key", "decimals", "network"] }, "description": "List of all supported currencies" } }, "required": ["data"] }, "Network": { "type": "object", "properties": { "key": { "type": "string", "description": "Network key/identifier (e.g., 'POLYGON', 'POLYGON_AMOY')", "example": "POLYGON" }, "name": { "type": "string", "description": "Display name for the network (e.g., 'Polygon')", "example": "Polygon" } }, "required": ["key", "name"] }, "NetworksResponse": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Network key/identifier (e.g., 'POLYGON', 'POLYGON_AMOY')" }, "name": { "type": "string", "description": "Display name for the network (e.g., 'Polygon')" } }, "required": ["key", "name"] }, "description": "List of all supported networks", "type": "array" } }, "required": ["data"] }, "QuicknodeWebhookPayloadDto": { "anyOf": [ { "type": "object", "properties": { "matchingReceipts": { "type": "array", "items": { "type": "object", "properties": { "transactionHash": { "type": "string" }, "status": { "type": "string" }, "logs": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "blockHash": { "type": "string" }, "blockNumber": { "type": "string" }, "data": { "type": "string" }, "logIndex": { "type": "string" }, "removed": { "type": "boolean" }, "topics": { "type": "array", "items": { "type": "string" } }, "transactionHash": { "type": "string" }, "transactionIndex": { "type": "string" } }, "required": [ "address", "blockHash", "blockNumber", "data", "logIndex", "removed", "topics", "transactionHash", "transactionIndex" ] } }, { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "data": { "type": "string" }, "blockHash": { "type": "string", "nullable": true }, "blockNumber": { "type": "string", "nullable": true }, "transactionHash": { "type": "string" }, "transactionIndex": { "type": "string" }, "logIndex": { "type": "number" }, "removed": { "type": "boolean" } }, "required": ["address", "topics", "data"] } } ] }, "blockHash": { "type": "string" }, "blockNumber": { "type": "string" }, "contractAddress": { "type": "string", "nullable": true }, "cumulativeGasUsed": { "type": "string", "nullable": true }, "effectiveGasPrice": { "type": "string" }, "from": { "type": "string" }, "gasUsed": { "type": "string" }, "logsBloom": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "transactionIndex": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } }, "required": ["transactionHash", "status", "logs"] } }, "currentBlockNumber": { "type": "number", "nullable": true } }, "required": ["matchingReceipts"] }, { "type": "object", "properties": { "heartbeat": { "type": "boolean", "const": true }, "currentBlockNumber": { "type": "number", "nullable": true } }, "required": ["heartbeat", "currentBlockNumber"] } ] }, "CounterpartyData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the counterparty", "example": "550e8400-e29b-41d4-a716-446655440000" }, "workspace_id": { "type": "string", "description": "Workspace ID the counterparty belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "classification": { "type": "string", "description": "Classification: individual (person) or business (company)", "enum": ["individual", "business"], "example": "business" }, "tenant_id": { "type": "string", "nullable": true, "description": "Optional reference to a tenant entity this counterparty belongs to", "example": "550e8400-e29b-41d4-a716-446655440002" }, "individual_first_name": { "type": "string", "nullable": true, "description": "First name (for individuals)", "example": "John" }, "individual_last_name": { "type": "string", "nullable": true, "description": "Last name (for individuals)", "example": "Doe" }, "individual_address_country": { "type": "string", "nullable": true, "description": "Country code in ISO 3166-1 format (for individuals)", "example": "US" }, "individual_date_of_birth": { "type": "string", "nullable": true, "description": "Date of birth (for individuals)", "example": "1980-01-01" }, "individual_national_identification_number": { "type": "string", "nullable": true, "description": "National identification number (for individuals)", "example": "123456789" }, "individual_street_address1": { "type": "string", "nullable": true, "description": "Street address line 1 (for individuals)", "example": "123 Main St" }, "individual_street_address2": { "type": "string", "nullable": true, "description": "Street address line 2 (for individuals)", "example": "Apt 4B" }, "individual_city": { "type": "string", "nullable": true, "description": "City (for individuals)", "example": "New York" }, "individual_state": { "type": "string", "nullable": true, "description": "State/region (for individuals)", "example": "NY" }, "individual_postal_code": { "type": "string", "nullable": true, "description": "Postal code (for individuals)", "example": "10001" }, "business_legal_name": { "type": "string", "nullable": true, "description": "Legal business name (for businesses)", "example": "Acme Corporation" }, "business_dba": { "type": "string", "nullable": true, "description": "DBA - Doing Business As (for businesses)", "example": "Acme Co" }, "business_address_country": { "type": "string", "nullable": true, "description": "Country code in ISO 3166-1 format (for businesses)", "example": "US" }, "business_street_address1": { "type": "string", "nullable": true, "description": "Street address line 1 (for businesses)", "example": "456 Corp Blvd" }, "business_street_address2": { "type": "string", "nullable": true, "description": "Street address line 2 (for businesses)", "example": "Suite 200" }, "business_city": { "type": "string", "nullable": true, "description": "City (for businesses)", "example": "San Francisco" }, "business_state": { "type": "string", "nullable": true, "description": "State/region (for businesses)", "example": "CA" }, "business_legal_entity_identifier": { "type": "string", "nullable": true, "description": "Legal Entity Identifier (for businesses)", "example": "1234567890" }, "created_at": { "type": "string", "description": "Creation timestamp in ISO 8601 format", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "type": "string", "description": "Last update timestamp in ISO 8601 format", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "workspace_id", "classification", "created_at", "updated_at" ] }, "CreateCounterpartyResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CounterpartyData" } }, "required": ["data"] }, "CounterpartyListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CounterpartyData" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "CounterpartyResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CounterpartyData" } }, "required": ["data"] }, "CreateCounterpartyRequestDto": { "type": "object", "properties": { "classification": { "type": "string", "description": "Classification: 'individual' or 'business'.", "enum": ["individual", "business"], "example": "individual" }, "tenant_id": { "type": "string", "description": "ID of the tenant entity (optional).", "example": "550e8400-e29b-41d4-a716-446655440002", "nullable": true, "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "individual_first_name": { "type": "string", "description": "First name (required if classification is 'individual'). Secure field, returned based on include_secure.", "maxLength": 255, "example": "John", "nullable": true }, "individual_last_name": { "type": "string", "description": "Last name (required if classification is 'individual'). Secure field, returned based on include_secure.", "maxLength": 255, "example": "Doe", "nullable": true }, "individual_address_country": { "type": "string", "description": "ISO 3166-1 alpha-2 or alpha-3 country code.", "minLength": 2, "maxLength": 3, "pattern": "^[A-Za-z]{2,3}$", "example": "US", "nullable": true }, "individual_date_of_birth": { "type": "string", "description": "Date of birth (for individuals).", "maxLength": 255, "example": "1980-01-01", "nullable": true }, "individual_national_identification_number": { "type": "string", "description": "National identification number (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "123456789", "nullable": true }, "individual_street_address1": { "type": "string", "description": "Street address line 1 (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "123 Main St", "nullable": true }, "individual_street_address2": { "type": "string", "description": "Street address line 2 (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "Apt 4B", "nullable": true }, "individual_city": { "type": "string", "description": "City (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "New York", "nullable": true }, "individual_state": { "type": "string", "description": "State/region (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "NY", "nullable": true }, "individual_postal_code": { "type": "string", "description": "Postal code (for individuals). Secure field, returned based on include_secure.", "maxLength": 255, "example": "10001", "nullable": true }, "business_legal_name": { "type": "string", "description": "Legal business name (required if classification is 'business').", "maxLength": 255, "example": "Acme Corporation", "nullable": true }, "business_dba": { "type": "string", "description": "Doing Business As name (optional).", "maxLength": 255, "example": "Acme Co", "nullable": true }, "business_address_country": { "type": "string", "description": "ISO 3166-1 alpha-2 or alpha-3 country code.", "minLength": 2, "maxLength": 3, "pattern": "^[A-Za-z]{2,3}$", "example": "US", "nullable": true }, "business_street_address1": { "type": "string", "description": "Street address line 1 (for businesses).", "maxLength": 255, "example": "456 Corp Blvd", "nullable": true }, "business_street_address2": { "type": "string", "description": "Street address line 2 (for businesses).", "maxLength": 255, "example": "Suite 200", "nullable": true }, "business_city": { "type": "string", "description": "City (for businesses).", "maxLength": 255, "example": "San Francisco", "nullable": true }, "business_state": { "type": "string", "description": "State/region (for businesses).", "maxLength": 255, "example": "CA", "nullable": true }, "business_legal_entity_identifier": { "type": "string", "description": "Legal Entity Identifier (for businesses). Secure field, returned based on include_secure.", "maxLength": 255, "example": "1234567890", "nullable": true } }, "required": ["classification"] }, "TenantData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the tenant", "example": "550e8400-e29b-41d4-a716-446655440000" }, "workspace_id": { "type": "string", "description": "Workspace ID the tenant belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "name": { "type": "string", "description": "Display name derived from business fields", "example": "Acme Corporation" }, "business_legal_name": { "type": "string", "nullable": true, "description": "Legal business name", "example": "Acme Corporation" }, "business_dba": { "type": "string", "nullable": true, "description": "DBA - Doing Business As", "example": "Acme Co" }, "business_address_country": { "type": "string", "nullable": true, "description": "Country code in ISO 3166-1 format", "example": "US" }, "webhook_url": { "type": "string", "nullable": true, "description": "Webhook URL for payment creation notifications", "example": "https://your-api.com/webhooks/tesser" }, "business_street_address1": { "type": "string", "nullable": true, "description": "Street address line 1", "example": "456 Corp Blvd" }, "business_street_address2": { "type": "string", "nullable": true, "description": "Street address line 2", "example": "Suite 200" }, "business_city": { "type": "string", "nullable": true, "description": "City", "example": "San Francisco" }, "business_state": { "type": "string", "nullable": true, "description": "State/region", "example": "CA" }, "business_postal_code": { "type": "string", "nullable": true, "description": "Postal code", "example": "94105" }, "business_legal_entity_identifier": { "type": "string", "nullable": true, "description": "Legal Entity Identifier", "example": "1234567890" }, "created_at": { "type": "string", "description": "Creation timestamp in ISO 8601 format", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "type": "string", "description": "Last update timestamp in ISO 8601 format", "example": "2024-01-15T10:30:00.000Z" } }, "required": ["id", "workspace_id", "name", "created_at", "updated_at"] }, "CreateTenantData": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/TenantData" } }, "required": ["tenant"] }, "CreateTenantResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateTenantData" } }, "required": ["data"] }, "TenantListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TenantData" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "TenantResponseDto": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TenantData" } }, "required": ["data"] }, "CreateTenantRequestDto": { "type": "object", "properties": { "business_legal_name": { "type": "string", "description": "Legal business name (required)", "example": "Acme Corporation", "minLength": 1, "maxLength": 255 }, "business_dba": { "type": "string", "nullable": true, "description": "DBA - Doing Business As name", "example": "Acme Co", "maxLength": 255 }, "business_address_country": { "type": "string", "nullable": true, "description": "Country code in ISO 3166-1 alpha-2 or alpha-3 format", "example": "US", "minLength": 2, "maxLength": 3, "pattern": "^[A-Za-z]{2,3}$" }, "webhook_url": { "type": "string", "nullable": true, "description": "Webhook URL for payment creation notifications", "example": "https://your-api.com/webhooks/tesser", "format": "uri" }, "business_street_address1": { "type": "string", "nullable": true, "description": "Street address line 1", "maxLength": 255, "example": "456 Corp Blvd" }, "business_street_address2": { "type": "string", "nullable": true, "description": "Street address line 2", "maxLength": 255, "example": "Suite 200" }, "business_city": { "type": "string", "nullable": true, "description": "City", "maxLength": 255, "example": "San Francisco" }, "business_state": { "type": "string", "nullable": true, "description": "State/region", "maxLength": 255, "example": "CA" }, "business_postal_code": { "type": "string", "nullable": true, "description": "Postal code", "maxLength": 50, "example": "94105" }, "business_legal_entity_identifier": { "type": "string", "nullable": true, "description": "Legal Entity Identifier", "maxLength": 255, "example": "1234567890" } }, "required": ["business_legal_name"] }, "CreateApiKeyRequestDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": ["name"] }, "CreateApiKeyResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "maskedClientId": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "lastUsedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "description", "maskedClientId", "status", "lastUsedAt", "createdAt", "updatedAt" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string", "format": "uri" }, "audience": { "type": "string" } }, "required": [ "apiKey", "clientId", "clientSecret", "tokenEndpoint", "audience" ] } }, "required": ["message", "data"] }, "ListApiKeysResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "maskedClientId": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "lastUsedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "description", "maskedClientId", "status", "lastUsedAt", "createdAt", "updatedAt" ] } } }, "required": ["message", "data"] }, "ApiKeyDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "maskedClientId": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "lastUsedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "description", "maskedClientId", "status", "lastUsedAt", "createdAt", "updatedAt" ] }, "RevokeApiKeyResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "maskedClientId": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "lastUsedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "description", "maskedClientId", "status", "lastUsedAt", "createdAt", "updatedAt" ] } }, "required": ["apiKey"] } }, "required": ["message", "data"] }, "DeleteApiKeyResponseDto": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "UpdateRiskProfileRequest": { "type": "object", "properties": { "risk_profile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "The risk profile for compliance screening" } }, "required": ["risk_profile"] }, "UpdateRiskProfileResponse": { "type": "object", "properties": { "risk_profile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "New risk profile" }, "old_risk_profile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "Previous risk profile" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Timestamp of the update" } }, "required": ["risk_profile", "old_risk_profile", "updated_at"] }, "RiskProfileResponse": { "type": "object", "properties": { "risk_profile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "Current risk profile" } }, "required": ["risk_profile"] }, "CreateSecretRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": ["CIRCLE_MINT", "OPENFX", "CIRCLE_PAYMENTS_NETWORK"], "description": "The secret provider (CIRCLE_MINT, OPENFX, or CIRCLE_PAYMENTS_NETWORK)" }, "key": { "type": "string", "enum": [ "CIRCLE_MINT_API_KEY", "OPENFX_CREDENTIALS", "CIRCLE_PAYMENTS_NETWORK_API_KEY" ], "description": "The secret key name (must be a known organization secret key)" }, "value": { "anyOf": [ { "type": "string", "minLength": 1, "description": "Single-string secret value (used by CIRCLE_MINT_API_KEY and CIRCLE_PAYMENTS_NETWORK_API_KEY)" }, { "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1, "description": "OpenFX organization UUID" }, "apiKey": { "type": "string", "minLength": 1, "description": "OpenFX API key identifier (used in JWT subject and x-api-key header)" }, "privateKey": { "type": "string", "minLength": 1, "description": "ES256 PEM private key used to sign short-lived OpenFX JWTs. Literal `\\n` escapes are normalized to real newlines." }, "webhookSecret": { "type": "string", "minLength": 1, "description": "HMAC-SHA256 signing key used to verify OpenFX webhook signatures" } }, "required": ["orgId", "apiKey", "privateKey", "webhookSecret"], "description": "OpenFX brokerage credentials bundle" } ], "description": "Secret payload. A string for single-value secrets, or an object for bundled credentials (e.g., OPENFX_CREDENTIALS)." } }, "required": ["provider", "key", "value"] }, "CreateSecretResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the secret was stored successfully" }, "masked_value": { "type": "string", "description": "Masked version of the stored secret (e.g., '****abc123')" } }, "required": ["success", "masked_value"] }, "SignupRequestDto": { "type": "object", "properties": { "entityName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": ["entityName", "email"] }, "SignupResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "teamId": { "type": "string" } }, "required": ["id", "email", "teamId"] }, "isNewTeam": { "type": "boolean" }, "isNewUser": { "type": "boolean" } }, "required": ["team", "user", "isNewTeam", "isNewUser"] } }, "required": ["message", "data"] }, "UserProfileDto": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "email", "teamId", "createdAt", "updatedAt"] }, "TeamDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "turnkeySubOrgId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "name", "createdAt", "updatedAt"] }, "UserProfileDataDto": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserProfileDto" }, "team": { "$ref": "#/components/schemas/TeamDto" } }, "required": ["user", "team"] }, "UserProfileResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/UserProfileDataDto" } }, "required": ["message", "data"] }, "PaymentDesiredFromLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentDesiredToLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentDesiredOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/PaymentDesiredFromLegResponse" }, "to": { "$ref": "#/components/schemas/PaymentDesiredToLegResponse" } }, "description": "Caller's stated intent at creation. Frozen except by the two-step PATCH flow which fills account IDs.", "required": ["from", "to"] }, "PaymentEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/PaymentEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/PaymentEstimatedToLeg" } }, "description": "Tesser's projection for how the payment will proceed.", "required": ["from", "to"] }, "PaymentActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/PaymentActualFromLeg" }, "to": { "$ref": "#/components/schemas/PaymentActualToLeg" } }, "description": "What actually settled. Populated once at least one step has `status: completed`.", "required": ["from", "to"] }, "RiskStatusReason": { "type": "object", "properties": { "risk_status_reason_type": { "type": "string" }, "risk_status_reason_category": { "type": "string" }, "risk_status_reason_message": { "type": "string" }, "risk_status_reason_severity": { "type": "string" } }, "required": [ "risk_status_reason_type", "risk_status_reason_category", "risk_status_reason_message", "risk_status_reason_severity" ] }, "PaymentStepEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentStepEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentStepEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/PaymentStepEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/PaymentStepEstimatedToLeg" } }, "description": "Planned values for this step.", "required": ["from", "to"] }, "PaymentStepActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentStepActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "PaymentStepActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/PaymentStepActualFromLeg" }, "to": { "$ref": "#/components/schemas/PaymentStepActualToLeg" } }, "description": "Settled values once the step reaches `status: completed`. All-null until then; remains all-null on failure.", "required": ["from", "to"] }, "StepFee": { "type": "object", "properties": { "fee_amount": { "type": "string", "description": "Fee amount." }, "fee_currency": { "type": "string", "description": "Fee currency code." }, "fee_type": { "type": "string", "description": "Fee type (e.g., 'gas', 'provider')." }, "fee_metadata": { "type": "object", "description": "Additional metadata for the fee (JSON object).", "additionalProperties": true } }, "required": ["fee_amount", "fee_currency", "fee_type"] }, "StatusReason": { "type": "object", "properties": { "error_code": { "type": "string", "example": "transfers-9201" }, "error_message": { "type": "string", "example": "An upstream step failed, so this step was not executed" } }, "required": ["error_code", "error_message"] }, "PaymentStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "payment_id": { "type": "string", "description": "ID of the parent payment", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e" }, "step_sequence": { "type": "integer", "description": "Order of this step in the payment flow (1-based)", "example": 1 }, "step_type": { "type": "string", "description": "Type of step", "enum": ["transfer", "swap"], "example": "transfer" }, "estimated": { "description": "Planned values for this step.", "allOf": [ { "$ref": "#/components/schemas/PaymentStepEstimatedOverlay" } ] }, "actual": { "description": "Settled values once the step reaches a terminal state. All-null until then.", "allOf": [ { "$ref": "#/components/schemas/PaymentStepActualOverlay" } ] }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash", "nullable": true, "example": null }, "unsigned_transaction": { "type": "string", "description": "Unsigned transaction bytes for client signing. Present only for Turnkey-signed steps in `signature_requested` status.", "nullable": true }, "fees": { "description": "Fees associated with this step.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StepFee" } }, "provider_key": { "type": "string", "description": "Provider used for this step", "nullable": true, "enum": ["circle_mint", "openfx", "turnkey"], "example": null }, "status": { "type": "string", "description": "Current status of this step", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "completed", "failed" ], "example": "completed" }, "status_reasons": { "description": "Reasons for the current status", "nullable": true, "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StatusReason" } }, "created_at": { "type": "string", "description": "Step creation timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Step last update timestamp", "format": "date-time", "example": "2024-03-01T10:02:00.000Z" }, "submitted_at": { "type": "string", "description": "Timestamp when step was submitted", "format": "date-time", "nullable": true, "example": null }, "confirmed_at": { "type": "string", "description": "Timestamp when step was confirmed", "format": "date-time", "nullable": true, "example": null }, "completed_at": { "type": "string", "description": "Timestamp when step completed", "format": "date-time", "nullable": true, "example": null }, "failed_at": { "type": "string", "description": "Timestamp when step failed", "format": "date-time", "nullable": true, "example": null } }, "required": [ "id", "payment_id", "step_sequence", "step_type", "estimated", "actual", "fees", "status", "created_at", "updated_at" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment identifier", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e" }, "workspace_id": { "type": "string", "description": "Workspace ID the payment belongs to", "example": "b53f6690-3242-4942-9907-885779632832" }, "organization_reference_id": { "type": "string", "description": "External reference ID for tracking.", "nullable": true, "example": "ref_123" }, "direction": { "type": "string", "description": "Payment direction.", "enum": ["inbound", "outbound", "rebalance"], "example": "outbound" }, "funding_account_id": { "type": "string", "description": "Funding account ID. Payment-only field. Top-level (not part of any overlay).", "nullable": true, "example": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a" }, "desired": { "description": "Caller's stated intent at creation. Frozen except by the two-step PATCH flow which fills account IDs.", "allOf": [ { "$ref": "#/components/schemas/PaymentDesiredOverlay" } ] }, "estimated": { "description": "Tesser's projection for how the payment will proceed.", "allOf": [ { "$ref": "#/components/schemas/PaymentEstimatedOverlay" } ] }, "actual": { "description": "What actually settled. Populated once at least one step has `status: completed`.", "allOf": [ { "$ref": "#/components/schemas/PaymentActualOverlay" } ] }, "risk_status": { "type": "string", "description": "Risk assessment status.", "enum": [ "unchecked", "awaiting_decision", "automatically_approved", "manually_approved", "automatically_rejected", "manually_rejected" ], "example": "unchecked" }, "risk_status_reasons": { "description": "Reasons for risk status.", "nullable": true, "example": [], "type": "array", "items": { "$ref": "#/components/schemas/RiskStatusReason" } }, "risk_reviewed_by": { "type": "string", "description": "User ID who reviewed the risk.", "nullable": true, "example": null }, "risk_reviewed_at": { "type": "string", "description": "Timestamp when risk was reviewed.", "format": "date-time", "nullable": true, "example": null }, "balance_status": { "type": "string", "description": "Balance reservation status.", "nullable": true, "enum": ["unreserved", "awaiting_funds", "reserved"], "example": "unreserved" }, "balance_reserved_at": { "type": "string", "description": "Timestamp when balance was reserved.", "format": "date-time", "nullable": true, "example": null }, "steps": { "description": "Payment execution steps.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/PaymentStep" } }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation.", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp when the payment expires.", "format": "date-time", "nullable": true, "example": "2024-03-02T10:00:00.000Z" } }, "required": [ "id", "workspace_id", "direction", "funding_account_id", "desired", "estimated", "actual", "risk_status", "balance_status", "balance_reserved_at", "steps", "created_at", "updated_at", "expires_at" ] }, "PaymentResponse": { "type": "object", "properties": { "data": { "description": "Payment data", "allOf": [ { "$ref": "#/components/schemas/Payment" } ] } }, "required": ["data"] }, "ListPaymentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "LegacyPaymentFee": { "type": "object", "properties": { "fee_amount": { "type": "string", "example": "1000" }, "fee_currency": { "type": "string", "example": "USDC" }, "fee_type": { "type": "string", "example": "gas" }, "fee_metadata": { "type": "object", "nullable": true, "additionalProperties": true, "example": {} } }, "required": ["fee_amount", "fee_currency", "fee_type"] }, "LegacyPaymentStep": { "type": "object", "properties": { "id": { "type": "string", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "payment_id": { "type": "string", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e" }, "step_sequence": { "type": "integer", "example": 1 }, "step_type": { "type": "string", "enum": ["transfer", "swap"], "example": "transfer" }, "from_account_id": { "type": "string", "nullable": true }, "from_amount": { "type": "string", "example": "1000000" }, "from_network": { "type": "string", "nullable": true }, "from_currency": { "type": "string", "example": "USDC" }, "to_account_id": { "type": "string", "nullable": true }, "to_amount": { "type": "string", "example": "999000" }, "to_network": { "type": "string", "nullable": true }, "to_currency": { "type": "string", "example": "USDC" }, "transaction_hash": { "type": "string", "nullable": true }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyPaymentFee" } }, "provider_key": { "type": "string", "nullable": true, "enum": ["circle_mint", "turnkey"] }, "status": { "type": "string", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "completed", "failed" ] }, "status_reasons": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StatusReason" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "payment_id", "step_sequence", "step_type", "from_amount", "from_currency", "to_amount", "to_currency", "status", "created_at", "updated_at" ] }, "PaymentTableEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Entity unique identifier" }, "classification": { "type": "string", "description": "Entity classification: 'individual' or 'business'", "enum": ["individual", "business"] }, "business_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "business_country": { "type": "string", "nullable": true }, "individual_country": { "type": "string", "nullable": true }, "wallet_address": { "type": "string", "nullable": true } }, "required": ["id", "classification"] }, "FundingAccount": { "type": "object", "properties": { "id": { "type": "string", "description": "Account unique identifier" }, "name": { "type": "string", "description": "Account name" }, "bank_name": { "type": "string", "nullable": true }, "bank_identifier_code": { "type": "string", "nullable": true }, "bank_swift_code": { "type": "string", "nullable": true } }, "required": ["id", "name"] }, "InternalPaymentFull": { "type": "object", "properties": { "id": { "type": "string", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e" }, "workspace_id": { "type": "string", "example": "b53f6690-3242-4942-9907-885779632832" }, "organization_reference_id": { "type": "string", "nullable": true }, "direction": { "type": "string", "enum": ["inbound", "outbound", "rebalance"], "example": "outbound" }, "funding_account_id": { "type": "string", "nullable": true }, "from_account_id": { "type": "string", "nullable": true }, "from_amount": { "type": "string", "example": "1000000" }, "from_network": { "type": "string", "nullable": true }, "from_currency": { "type": "string", "example": "USDC" }, "to_account_id": { "type": "string", "nullable": true }, "to_amount": { "type": "string", "example": "1000000" }, "to_network": { "type": "string", "nullable": true }, "to_currency": { "type": "string", "example": "USDC" }, "risk_status": { "type": "string", "nullable": true, "enum": [ "unchecked", "awaiting_decision", "automatically_approved", "manually_approved", "automatically_rejected", "manually_rejected" ] }, "risk_status_reasons": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/RiskStatusReason" } }, "risk_reviewed_by": { "type": "string", "nullable": true }, "risk_reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "balance_status": { "type": "string", "nullable": true, "enum": ["unreserved", "reserved", "awaiting_funds"] }, "balance_reserved_at": { "type": "string", "format": "date-time", "nullable": true }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyPaymentStep" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "originator": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentTableEntity" } ] }, "belongsTo": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentTableEntity" } ] }, "beneficiary": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentTableEntity" } ] }, "funding_account": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FundingAccount" } ] }, "status": { "type": "string", "description": "Computed payment status for UI", "enum": [ "queued", "processing", "ready-to-submit", "sent", "need-review", "compliance-blocked", "insufficient-balance" ] } }, "required": [ "id", "workspace_id", "direction", "from_amount", "from_currency", "to_amount", "to_currency", "risk_status", "created_at", "updated_at", "expires_at", "status" ] }, "InternalPaymentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InternalPaymentFull" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "ReviewPaymentRequest": { "type": "object", "properties": { "is_approved": { "type": "boolean", "description": "Approve (true) or reject (false) the payment." } }, "required": ["is_approved"] }, "PaymentDesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Source account ID. May be omitted at POST and supplied later via PATCH (two-step PATCH flow)." }, "amount": { "type": "string", "description": "Source amount. Exactly one of `desired.from.amount` or `desired.to.amount` must be supplied.", "example": "10.00" }, "currency": { "type": "string", "description": "Source currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Source blockchain network. Required when `desired.from.currency` is a stablecoin." } }, "description": "Source side of the payment.", "required": ["currency"] }, "PaymentDesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Destination account ID. May be omitted at POST and supplied later via PATCH (two-step PATCH flow)." }, "amount": { "type": "string", "description": "Destination amount. Exactly one of `desired.from.amount` or `desired.to.amount` must be supplied.", "example": "10.00" }, "currency": { "type": "string", "description": "Destination currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Destination blockchain network. Required for crypto-to-crypto payments." } }, "description": "Destination side of the payment.", "required": ["currency"] }, "PaymentDesiredOverlayRequest": { "type": "object", "properties": { "from": { "description": "Source side of the payment.", "allOf": [ { "$ref": "#/components/schemas/PaymentDesiredFromLeg" } ] }, "to": { "description": "Destination side of the payment.", "allOf": [ { "$ref": "#/components/schemas/PaymentDesiredToLeg" } ] } }, "description": "Caller's stated intent for the payment.", "required": ["from", "to"] }, "CreatePaymentRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional external reference ID for tracking." }, "funding_account_id": { "type": "string", "description": "Funding account ID. Optional at POST to support the two-step PATCH creation flow; required together with `desired.from.account_id` and `desired.to.account_id` once any of the three is supplied." }, "desired": { "description": "Caller's stated intent for the payment.", "allOf": [ { "$ref": "#/components/schemas/PaymentDesiredOverlayRequest" } ] } }, "required": ["desired"] }, "UpdatePaymentDesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Source account ID." } }, "description": "Source side of the payment (account-only update).", "required": ["account_id"] }, "UpdatePaymentDesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Destination account ID." } }, "description": "Destination side of the payment (account-only update).", "required": ["account_id"] }, "UpdatePaymentDesiredOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/UpdatePaymentDesiredFromLeg" }, "to": { "$ref": "#/components/schemas/UpdatePaymentDesiredToLeg" } }, "description": "Account-only update to the payment's desired overlay (two-step PATCH flow).", "required": ["from", "to"] }, "UpdatePaymentRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional external reference ID for tracking." }, "funding_account_id": { "type": "string", "description": "Funding account ID for the payment." }, "desired": { "description": "Account IDs to attach to the payment.", "allOf": [ { "$ref": "#/components/schemas/UpdatePaymentDesiredOverlay" } ] } }, "required": ["funding_account_id", "desired"] }, "SignPaymentStepRequest": { "type": "object", "properties": { "signature": { "type": "string", "minLength": 1, "description": "Base64-encoded JSON envelope `{ body, stamp }` where `body` is the JSON-encoded Turnkey `ACTIVITY_TYPE_SIGN_TRANSACTION_V2` activity and `stamp` is the X-Stamp header value produced by stamping that body. Wire format: `base64(JSON.stringify({ body, stamp }))`.", "example": "" } }, "required": ["signature"] }, "SimulateInboundPaymentRequest": { "type": "object", "properties": { "to_account": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Managed account ID that should receive the simulated inbound." }, "mocked_risk_status": { "type": "string", "enum": [ "automatically_approved", "awaiting_decision", "automatically_rejected" ], "description": "The risk_status the screening verdict should be forced to." }, "network": { "description": "EVM testnet to send on. Defaults to BASE_SEPOLIA.", "type": "string", "enum": ["BASE_SEPOLIA", "ETHEREUM_SEPOLIA", "POLYGON_AMOY"] } }, "required": ["to_account", "mocked_risk_status"] }, "CurrencyBalanceDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol", "example": "USDC" }, "available": { "type": "string", "description": "Available balance from managed accounts (sum across all networks)", "example": "250000000" }, "pendingReview": { "type": "string", "description": "Total payment amount pending review", "example": "50000000" }, "rejected": { "type": "string", "description": "Total payment amount rejected", "example": "20000000" } }, "required": ["currency", "available", "pendingReview", "rejected"] }, "TreasuryBalancesDataDto": { "type": "object", "properties": { "balances": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyBalanceDto" } } }, "required": ["balances"] }, "TreasuryBalancesResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/TreasuryBalancesDataDto" } }, "required": ["message", "data"] }, "DepositDesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositDesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Always null for deposits — see `estimated.to.amount` for the indicative target.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositDesiredOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/DepositDesiredFromLeg" }, "to": { "$ref": "#/components/schemas/DepositDesiredToLeg" } }, "description": "Caller's stated intent at creation. Frozen, never overwritten.", "required": ["from", "to"] }, "DepositEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/DepositEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/DepositEstimatedToLeg" } }, "description": "Tesser's projection for how the deposit will proceed.", "required": ["from", "to"] }, "DepositActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "DepositActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/DepositActualFromLeg" }, "to": { "$ref": "#/components/schemas/DepositActualToLeg" } }, "description": "What actually settled. Populated when the deposit reaches a terminal state.", "required": ["from", "to"] }, "StepEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "StepEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "StepEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/StepEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/StepEstimatedToLeg" } }, "description": "Planned values for this step.", "required": ["from", "to"] }, "StepActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "StepActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "StepActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/StepActualFromLeg" }, "to": { "$ref": "#/components/schemas/StepActualToLeg" } }, "description": "Settled values once the step reaches a terminal state. All-null until then.", "required": ["from", "to"] }, "DepositStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the step.", "example": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a" }, "deposit_id": { "type": "string", "description": "ID of the parent deposit.", "example": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e" }, "step_sequence": { "type": "integer", "description": "Step sequence number (1-based).", "example": 1 }, "step_type": { "type": "string", "description": "Step type: 'transfer', 'swap'.", "enum": ["transfer", "swap"], "example": "transfer" }, "estimated": { "description": "Planned values for this step.", "allOf": [ { "$ref": "#/components/schemas/StepEstimatedOverlay" } ] }, "actual": { "description": "Settled values once the step reaches a terminal state. All-null until then.", "allOf": [ { "$ref": "#/components/schemas/StepActualOverlay" } ] }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash (for crypto steps).", "example": null, "nullable": true }, "fees": { "description": "List of fees associated with this step.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StepFee" } }, "provider_key": { "type": "string", "description": "Provider key used for this step (if applicable).", "enum": ["circle_mint", "openfx", "turnkey"], "example": "circle_mint", "nullable": true }, "status": { "type": "string", "description": "Step status: 'created', 'signature_requested', 'signed', 'submitted', 'confirmed', 'completed', 'failed'.", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "completed", "failed" ], "example": "created" }, "status_reasons": { "description": "Array of reasons explaining the current status (if any).", "example": null, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/StatusReason" } }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation.", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-03-01T10:00:00.000Z" }, "submitted_at": { "type": "string", "description": "Submitted timestamp.", "example": null, "nullable": true }, "confirmed_at": { "type": "string", "description": "Confirmed timestamp.", "example": null, "nullable": true }, "completed_at": { "type": "string", "description": "Completed timestamp.", "example": null, "nullable": true }, "failed_at": { "type": "string", "description": "Failed timestamp.", "example": null, "nullable": true } }, "required": [ "id", "deposit_id", "step_sequence", "step_type", "estimated", "actual", "fees", "status", "created_at", "updated_at" ] }, "Deposit": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the deposit.", "example": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e" }, "workspace_id": { "type": "string", "description": "Workspace ID the deposit belongs to.", "example": "b53f6690-3242-4942-9907-885779632832" }, "organization_reference_id": { "type": "string", "description": "Optional external reference ID.", "example": null, "nullable": true }, "direction": { "type": "string", "description": "Resource direction.", "enum": ["inbound"], "example": "inbound" }, "desired": { "description": "Caller's stated intent at creation. Frozen, never overwritten.", "allOf": [ { "$ref": "#/components/schemas/DepositDesiredOverlay" } ] }, "estimated": { "description": "Tesser's projection for how the deposit will proceed.", "allOf": [ { "$ref": "#/components/schemas/DepositEstimatedOverlay" } ] }, "actual": { "description": "What actually settled. Populated when the deposit reaches a terminal state.", "allOf": [ { "$ref": "#/components/schemas/DepositActualOverlay" } ] }, "steps": { "description": "Optional list of system-generated steps that make up this deposit route.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/DepositStep" } }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation.", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp when the deposit expires, or null for auto-created deposits.", "example": "2024-03-01T14:00:00.000Z", "nullable": true } }, "required": [ "id", "workspace_id", "direction", "desired", "estimated", "actual", "created_at", "updated_at" ] }, "CreateDepositResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Deposit" } }, "required": ["data"] }, "DepositBankAccount": { "type": "object", "properties": { "id": { "type": "string", "description": "Account ID." }, "name": { "type": "string", "description": "Account name." }, "bank_name": { "type": "string", "description": "Bank name." }, "bank_account_number": { "type": "string", "description": "Bank account number." }, "bank_code_type": { "type": "string", "description": "Bank code type (e.g., 'routing')." }, "bank_identifier_code": { "type": "string", "description": "Bank identifier code (routing number, sort code, etc.)." }, "bank_swift_code": { "type": "string", "description": "Bank SWIFT code.", "nullable": true } }, "required": [ "id", "name", "bank_name", "bank_account_number", "bank_code_type", "bank_identifier_code" ] }, "BeneficiaryBusinessInfo": { "type": "object", "properties": { "business_legal_name": { "type": "string", "description": "Business legal name." }, "business_street_address1": { "type": "string", "description": "Street address line 1.", "nullable": true }, "business_street_address2": { "type": "string", "description": "Street address line 2.", "nullable": true }, "business_city": { "type": "string", "description": "City (null when address isn't structured).", "nullable": true }, "business_state": { "type": "string", "description": "State (null when address isn't structured).", "nullable": true }, "business_postal_code": { "type": "string", "description": "Postal code (null when address isn't structured).", "nullable": true }, "business_country": { "type": "string", "description": "Country code (null when address isn't structured).", "nullable": true } }, "required": ["business_legal_name"] }, "WireInstructionsBankAccount": { "type": "object", "properties": { "id": { "type": "string", "description": "Account ID." }, "name": { "type": "string", "description": "Account name." }, "bank_name": { "type": "string", "description": "Bank name." }, "bank_account_number": { "type": "string", "description": "Bank account number (VAN)." }, "bank_code_type": { "type": "string", "description": "Bank code type (e.g., ROUTING)." }, "bank_identifier_code": { "type": "string", "description": "Bank identifier code (routing number)." }, "bank_swift_code": { "type": "string", "description": "Bank SWIFT code (null for non-SWIFT rails like SPEI/SEPA).", "nullable": true }, "tracking_reference": { "type": "string", "description": "Wire transfer tracking reference.", "nullable": true }, "belongs_to": { "description": "Beneficiary business info (legal entity receiving the wire).", "allOf": [ { "$ref": "#/components/schemas/BeneficiaryBusinessInfo" } ] } }, "required": [ "id", "name", "bank_name", "bank_account_number", "bank_code_type", "bank_identifier_code", "belongs_to" ] }, "DepositInstructionsData": { "type": "object", "properties": { "from_account": { "description": "Source account information (for reference).", "allOf": [ { "$ref": "#/components/schemas/DepositBankAccount" } ] }, "to_account": { "description": "Wire instructions for completing the deposit.", "allOf": [ { "$ref": "#/components/schemas/WireInstructionsBankAccount" } ] }, "amount": { "type": "string", "description": "Deposit amount." }, "currency": { "type": "string", "description": "Deposit currency." } }, "required": ["from_account", "to_account", "amount", "currency"] }, "DepositInstructionsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepositInstructionsData" } }, "required": ["data"] }, "ListDepositsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "DesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Source bank account ID." }, "amount": { "type": "string", "description": "Source amount.", "example": "1000.00" }, "currency": { "type": "string", "description": "Source currency code.", "example": "USD" } }, "description": "Source side of the deposit.", "required": ["account_id", "amount", "currency"] }, "DesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Destination account ID." }, "currency": { "type": "string", "description": "Destination currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Destination blockchain network." } }, "description": "Destination side of the deposit.", "required": ["account_id", "currency"] }, "DesiredOverlayRequest": { "type": "object", "properties": { "from": { "description": "Source side of the deposit.", "allOf": [ { "$ref": "#/components/schemas/DesiredFromLeg" } ] }, "to": { "description": "Destination side of the deposit.", "allOf": [ { "$ref": "#/components/schemas/DesiredToLeg" } ] } }, "description": "Caller's stated intent for the deposit.", "required": ["from", "to"] }, "CreateDepositRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional client-supplied identifier." }, "desired": { "description": "Caller's stated intent for the deposit.", "allOf": [ { "$ref": "#/components/schemas/DesiredOverlayRequest" } ] } }, "required": ["desired"] }, "RebalanceDesiredFromLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceDesiredToLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceDesiredOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RebalanceDesiredFromLegResponse" }, "to": { "$ref": "#/components/schemas/RebalanceDesiredToLegResponse" } }, "description": "Caller's stated intent at creation. Frozen, never overwritten.", "required": ["from", "to"] }, "RebalanceEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RebalanceEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/RebalanceEstimatedToLeg" } }, "description": "Tesser's projection for how the rebalance will proceed.", "required": ["from", "to"] }, "RebalanceActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RebalanceActualFromLeg" }, "to": { "$ref": "#/components/schemas/RebalanceActualToLeg" } }, "description": "What actually settled. Populated when the rebalance reaches a terminal state.", "required": ["from", "to"] }, "RebalanceStepEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceStepEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceStepEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RebalanceStepEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/RebalanceStepEstimatedToLeg" } }, "description": "Planned values for this step.", "required": ["from", "to"] }, "RebalanceStepActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceStepActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "RebalanceStepActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RebalanceStepActualFromLeg" }, "to": { "$ref": "#/components/schemas/RebalanceStepActualToLeg" } }, "description": "Settled values once the step reaches a terminal state. All-null until then.", "required": ["from", "to"] }, "RebalanceStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "rebalance_id": { "type": "string", "description": "ID of the parent rebalance", "example": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b" }, "step_sequence": { "type": "integer", "description": "Order of this step in the rebalance flow (1-based)", "example": 1 }, "step_type": { "type": "string", "description": "Type of step", "enum": ["transfer", "swap"], "example": "transfer" }, "estimated": { "description": "Planned values for this step.", "allOf": [ { "$ref": "#/components/schemas/RebalanceStepEstimatedOverlay" } ] }, "actual": { "description": "Settled values once the step reaches a terminal state. All-null until then.", "allOf": [ { "$ref": "#/components/schemas/RebalanceStepActualOverlay" } ] }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash", "nullable": true, "example": null }, "unsigned_transaction": { "type": "string", "description": "Unsigned transaction bytes for client signing. Present only for Turnkey-signed steps in signature_requested status.", "nullable": true }, "fees": { "description": "Fees associated with this step", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StepFee" } }, "provider_key": { "type": "string", "description": "Provider used for this step", "nullable": true, "enum": ["circle_mint", "turnkey"], "example": "circle_mint" }, "status": { "type": "string", "description": "Current status of this step", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "completed", "failed" ], "example": "completed" }, "status_reasons": { "description": "Reasons for the current status", "nullable": true, "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StatusReason" } }, "created_at": { "type": "string", "description": "Step creation timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Step last update timestamp", "format": "date-time", "example": "2024-03-01T10:02:30.000Z" }, "submitted_at": { "type": "string", "description": "Timestamp when step was submitted", "format": "date-time", "nullable": true, "example": "2024-03-01T10:00:10.000Z" }, "confirmed_at": { "type": "string", "description": "Timestamp when step was confirmed", "format": "date-time", "nullable": true, "example": "2024-03-01T10:02:00.000Z" }, "completed_at": { "type": "string", "description": "Timestamp when step completed", "format": "date-time", "nullable": true, "example": "2024-03-01T10:02:30.000Z" }, "failed_at": { "type": "string", "description": "Timestamp when step failed", "format": "date-time", "nullable": true, "example": null } }, "required": [ "id", "rebalance_id", "step_sequence", "step_type", "estimated", "actual", "fees", "status", "created_at", "updated_at" ] }, "Rebalance": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rebalance identifier", "example": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b" }, "workspace_id": { "type": "string", "description": "Workspace ID the rebalance belongs to", "example": "b53f6690-3242-4942-9907-885779632832" }, "organization_reference_id": { "type": "string", "description": "External reference ID for tracking", "nullable": true, "example": null }, "direction": { "type": "string", "description": "Resource direction.", "enum": ["rebalance"], "example": "rebalance" }, "desired": { "description": "Caller's stated intent at creation. Frozen, never overwritten.", "allOf": [ { "$ref": "#/components/schemas/RebalanceDesiredOverlay" } ] }, "estimated": { "description": "Tesser's projection for how the rebalance will proceed.", "allOf": [ { "$ref": "#/components/schemas/RebalanceEstimatedOverlay" } ] }, "actual": { "description": "What actually settled. Populated when the rebalance reaches a terminal state.", "allOf": [ { "$ref": "#/components/schemas/RebalanceActualOverlay" } ] }, "balance_status": { "type": "string", "description": "Balance reservation status.", "nullable": true, "enum": ["unreserved", "awaiting_funds", "reserved"], "example": null }, "balance_reserved_at": { "type": "string", "description": "Timestamp when balance was reserved.", "format": "date-time", "nullable": true, "example": null }, "steps": { "description": "Rebalance execution steps.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/RebalanceStep" } }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation.", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp when the rebalance expires.", "example": "2024-03-04T10:00:00.000Z", "nullable": true } }, "required": [ "id", "workspace_id", "direction", "desired", "estimated", "actual", "balance_status", "balance_reserved_at", "steps", "created_at", "updated_at", "expires_at" ] }, "RebalanceResponse": { "type": "object", "properties": { "data": { "description": "Rebalance data", "allOf": [ { "$ref": "#/components/schemas/Rebalance" } ] } }, "required": ["data"] }, "ListRebalancesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rebalance" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "RebalanceDesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Source account ID." }, "amount": { "type": "string", "description": "Source amount.", "example": "1000.00" }, "currency": { "type": "string", "description": "Source currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Source blockchain network." } }, "description": "Source side of the rebalance.", "required": ["account_id", "amount", "currency"] }, "RebalanceDesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Destination account ID." }, "currency": { "type": "string", "description": "Destination currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Destination blockchain network." } }, "description": "Destination side of the rebalance.", "required": ["account_id", "currency"] }, "RebalanceDesiredOverlayRequest": { "type": "object", "properties": { "from": { "description": "Source side of the rebalance.", "allOf": [ { "$ref": "#/components/schemas/RebalanceDesiredFromLeg" } ] }, "to": { "description": "Destination side of the rebalance.", "allOf": [ { "$ref": "#/components/schemas/RebalanceDesiredToLeg" } ] } }, "description": "Caller's stated intent for the rebalance.", "required": ["from", "to"] }, "CreateRebalanceRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional client-supplied identifier." }, "desired": { "description": "Caller's stated intent for the rebalance.", "allOf": [ { "$ref": "#/components/schemas/RebalanceDesiredOverlayRequest" } ] } }, "required": ["desired"] }, "SignRebalanceStepRequest": { "type": "object", "properties": { "signature": { "type": "string", "minLength": 1, "description": "Base64-encoded JSON envelope `{ body, stamp }` where `body` is the JSON-encoded Turnkey ACTIVITY_TYPE_SIGN_TRANSACTION_V2 activity and `stamp` is the X-Stamp header value produced by stamping that body. Tesser forwards the envelope to Turnkey to obtain the signed transaction." } }, "required": ["signature"] }, "WithdrawalDesiredFromLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalDesiredToLegResponse": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalDesiredOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/WithdrawalDesiredFromLegResponse" }, "to": { "$ref": "#/components/schemas/WithdrawalDesiredToLegResponse" } }, "description": "Caller's stated intent at creation. Frozen, never overwritten.", "required": ["from", "to"] }, "WithdrawalEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/WithdrawalEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/WithdrawalEstimatedToLeg" } }, "description": "Tesser's projection for how the withdrawal will proceed.", "required": ["from", "to"] }, "WithdrawalActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/WithdrawalActualFromLeg" }, "to": { "$ref": "#/components/schemas/WithdrawalActualToLeg" } }, "description": "What actually settled. Populated when the withdrawal reaches a terminal state.", "required": ["from", "to"] }, "WithdrawalStepEstimatedFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalStepEstimatedToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalStepEstimatedOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/WithdrawalStepEstimatedFromLeg" }, "to": { "$ref": "#/components/schemas/WithdrawalStepEstimatedToLeg" } }, "description": "Planned values for this step.", "required": ["from", "to"] }, "WithdrawalStepActualFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Source side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalStepActualToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Account ID.", "nullable": true }, "amount": { "type": "string", "description": "Amount.", "nullable": true }, "currency": { "type": "string", "description": "Currency code.", "nullable": true }, "network": { "type": "string", "description": "Blockchain network.", "nullable": true } }, "description": "Destination side.", "required": ["account_id", "amount", "currency", "network"] }, "WithdrawalStepActualOverlay": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/WithdrawalStepActualFromLeg" }, "to": { "$ref": "#/components/schemas/WithdrawalStepActualToLeg" } }, "description": "Settled values once the step reaches a terminal state. All-null until then.", "required": ["from", "to"] }, "WithdrawalStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "withdrawal_id": { "type": "string", "description": "ID of the parent withdrawal", "example": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a" }, "step_sequence": { "type": "integer", "description": "Order of this step in the withdrawal flow (1-based)", "example": 1 }, "step_type": { "type": "string", "description": "Type of step", "enum": ["transfer", "swap"], "example": "transfer" }, "estimated": { "description": "Planned values for this step.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalStepEstimatedOverlay" } ] }, "actual": { "description": "Settled values once the step reaches a terminal state. All-null until then.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalStepActualOverlay" } ] }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash", "nullable": true, "example": null }, "unsigned_transaction": { "type": "string", "description": "Unsigned transaction bytes for client signing. Present only for Turnkey-signed steps in signature_requested status.", "nullable": true }, "fees": { "description": "Fees associated with this step", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StepFee" } }, "provider_key": { "type": "string", "description": "Provider used for this step", "nullable": true, "enum": ["circle_mint", "turnkey", "openfx"], "example": "circle_mint" }, "status": { "type": "string", "description": "Current status of this step", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "completed", "failed" ], "example": "created" }, "status_reasons": { "description": "Reasons for the current status", "nullable": true, "example": [], "type": "array", "items": { "$ref": "#/components/schemas/StatusReason" } }, "created_at": { "type": "string", "description": "Step creation timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Step last update timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "submitted_at": { "type": "string", "description": "Timestamp when step was submitted", "format": "date-time", "nullable": true, "example": null }, "confirmed_at": { "type": "string", "description": "Timestamp when step was confirmed", "format": "date-time", "nullable": true, "example": null }, "completed_at": { "type": "string", "description": "Timestamp when step completed", "format": "date-time", "nullable": true, "example": null }, "failed_at": { "type": "string", "description": "Timestamp when step failed", "format": "date-time", "nullable": true, "example": null } }, "required": [ "id", "withdrawal_id", "step_sequence", "step_type", "estimated", "actual", "fees", "status", "created_at", "updated_at" ] }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique withdrawal identifier", "example": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a" }, "workspace_id": { "type": "string", "description": "Workspace ID the withdrawal belongs to", "example": "b53f6690-3242-4942-9907-885779632832" }, "organization_reference_id": { "type": "string", "description": "External reference ID for tracking", "nullable": true, "example": null }, "direction": { "type": "string", "description": "Resource direction.", "enum": ["outbound"], "example": "outbound" }, "desired": { "description": "Caller's stated intent at creation. Frozen, never overwritten.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalDesiredOverlay" } ] }, "estimated": { "description": "Tesser's projection for how the withdrawal will proceed.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalEstimatedOverlay" } ] }, "actual": { "description": "What actually settled. Populated when the withdrawal reaches a terminal state.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalActualOverlay" } ] }, "balance_status": { "type": "string", "description": "Balance reservation status.", "nullable": true, "enum": ["unreserved", "awaiting_funds", "reserved"], "example": "unreserved" }, "balance_reserved_at": { "type": "string", "description": "Timestamp when balance was reserved.", "format": "date-time", "nullable": true, "example": null }, "steps": { "description": "Withdrawal execution steps.", "example": [], "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalStep" } }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation.", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last update.", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "ISO 8601 timestamp when the withdrawal expires.", "example": "2024-03-01T14:00:00.000Z", "nullable": true } }, "required": [ "id", "workspace_id", "direction", "desired", "estimated", "actual", "balance_status", "balance_reserved_at", "steps", "created_at", "updated_at", "expires_at" ] }, "WithdrawalResponse": { "type": "object", "properties": { "data": { "description": "Withdrawal data", "allOf": [ { "$ref": "#/components/schemas/Withdrawal" } ] } }, "required": ["data"] }, "ListWithdrawalsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "WithdrawalDesiredFromLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Source account ID." }, "amount": { "type": "string", "description": "Source amount.", "example": "1000.00" }, "currency": { "type": "string", "description": "Source currency code.", "example": "USDC" }, "network": { "type": "string", "description": "Source blockchain network. Required when source is a self-custodial wallet." } }, "description": "Source side of the withdrawal.", "required": ["account_id", "amount", "currency"] }, "WithdrawalDesiredToLeg": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Destination bank account ID." }, "currency": { "type": "string", "description": "Destination currency code.", "example": "USD" } }, "description": "Destination side of the withdrawal.", "required": ["account_id", "currency"] }, "WithdrawalDesiredOverlayRequest": { "type": "object", "properties": { "from": { "description": "Source side of the withdrawal.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalDesiredFromLeg" } ] }, "to": { "description": "Destination side of the withdrawal.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalDesiredToLeg" } ] } }, "description": "Caller's stated intent for the withdrawal.", "required": ["from", "to"] }, "CreateWithdrawalRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional client-supplied identifier." }, "desired": { "description": "Caller's stated intent for the withdrawal.", "allOf": [ { "$ref": "#/components/schemas/WithdrawalDesiredOverlayRequest" } ] } }, "required": ["desired"] }, "SignWithdrawalStepRequest": { "type": "object", "properties": { "signature": { "type": "string", "minLength": 1, "description": "Base64-encoded JSON envelope `{ body, stamp }` where `body` is the JSON-encoded Turnkey ACTIVITY_TYPE_SIGN_TRANSACTION_V2 activity and `stamp` is the X-Stamp header value produced by stamping that body. Tesser forwards the envelope to Turnkey to obtain the signed transaction." } }, "required": ["signature"] } } }, "security": [ { "bearer": [] } ] }