{ "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": "entityType", "required": false, "in": "query", "description": "Filter by entity type (alias for entity_type)", "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": "US Dollar", "key": "USD", "decimals": 2, "network": null }, { "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" } ] } } } }, "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/kyb/all-status": { "get": { "operationId": "kYB_getTeamKYBStatus", "parameters": [], "responses": { "200": { "description": "Team provider status matrix retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get comprehensive provider status matrix (KYB + fiat accounts) for the authenticated team", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/fiat-accounts": { "post": { "operationId": "kYB_createFiatAccount", "parameters": [], "responses": { "201": { "description": "Fiat account created successfully" }, "400": { "description": "Invalid request data" } }, "security": [ { "bearer": [] } ], "summary": "Create a fiat account for the organization", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } }, "get": { "operationId": "kYB_getFiatAccounts", "parameters": [], "responses": { "200": { "description": "Fiat accounts retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get fiat accounts for the team", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/fiat-accounts/by-provider": { "get": { "operationId": "kYB_getFiatAccountsByProvider", "parameters": [], "responses": { "200": { "description": "All fiat accounts for provider retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get all fiat accounts for a provider", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/fiat-accounts/requirements": { "get": { "operationId": "kYB_getFiatAccountRequirements", "parameters": [], "responses": { "200": { "description": "Fiat account requirements retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get fiat account requirements for an account type", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/fiat-accounts/{id}": { "delete": { "operationId": "kYB_deleteFiatAccount", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fiat account deleted successfully" }, "404": { "description": "Fiat account not found" } }, "security": [ { "bearer": [] } ], "summary": "Delete a fiat account", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/new": { "post": { "operationId": "kYB_startKYBFlow", "parameters": [], "responses": { "200": { "description": "KYB flow initiated successfully" }, "400": { "description": "Invalid request data" } }, "security": [ { "bearer": [] } ], "summary": "Start KYB verification flow for organization (with auto-registration)", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/providers": { "get": { "operationId": "kYB_getProvidersAndCountries", "parameters": [], "responses": { "200": { "description": "Available providers and countries retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get available KYB providers and supported countries", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/started": { "post": { "operationId": "kYB_startMockKYBProgression", "parameters": [], "responses": { "200": { "description": "Mock KYB progression started" }, "404": { "description": "KYB record not found" } }, "security": [ { "bearer": [] } ], "summary": "Start mock KYB progression for testing (non-production only)", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/kyb/status": { "get": { "operationId": "kYB_getKYBStatus", "parameters": [], "responses": { "200": { "description": "KYB status retrieved successfully" }, "404": { "description": "KYB record not found" } }, "security": [ { "bearer": [] } ], "summary": "Get KYB status for organization", "tags": ["kyb"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-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": "POLYGON", "name": "Polygon" }, { "key": "SOLANA", "name": "Solana" }, { "key": "STELLAR", "name": "Stellar" } ] } } } }, "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/org-users": { "get": { "operationId": "orgUsers_listOrgUsers", "parameters": [], "responses": { "200": { "description": "Successfully retrieved org users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgUsersResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List all org users", "tags": ["Org 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" ] } } }, "post": { "operationId": "orgUsers_createUser", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequestDto" } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create user directly", "tags": ["Org 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/org-users/{userId}": { "get": { "operationId": "orgUsers_getOrgUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved org user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUserDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a specific org user", "tags": ["Org 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" ] } } }, "put": { "operationId": "orgUsers_updateUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequestDto" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserResponseDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update user directly", "tags": ["Org 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" ] } } }, "delete": { "operationId": "orgUsers_deleteUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User deleted successfully" } }, "security": [ { "bearer": [] } ], "summary": "Delete user directly", "tags": ["Org 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/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\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": "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/PaymentListResponse" }, "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": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "auto_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", "transfer_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "999000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123...", "fees": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": null, "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", "finalized_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-02T10:00:00.000Z" }, { "id": "1e7a4c8f-9b3d-4e25-b0f6-2c5d8a1f3b9e", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_123", "direction": "outbound", "funding_account_id": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "50000", "to_network": "ETHEREUM", "to_currency": "USD", "risk_status": "awaiting_decision", "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", "transfer_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "999000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123...", "fees": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": null, "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", "finalized_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-02T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 25, "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" } ] } } } } } }, "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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC" } } } } } }, "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": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": null, "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "unchecked", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": null, "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-02T10: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": "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": "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/PaymentListResponse" } } } }, "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/{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": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "auto_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", "transfer_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "999000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123...", "fees": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": null, "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", "finalized_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-02T10: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", "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": "9f3b7e1c-4a2d-4f69-b5a8-0c6e2d9f1a3b", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": "ref_456", "direction": "outbound", "funding_account_id": "2113b166-5873-42fd-85fe-5b1a02940d43", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "unchecked", "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": null, "balance_reserved_at": null, "steps": [], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:30:00.000Z", "expires_at": "2024-03-02T10: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": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "awaiting_decision", "risk_status_reasons": [ { "risk_status_reason_type": "ownership", "risk_status_reason_category": "Malware", "risk_status_reason_severity": "high" } ], "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", "transfer_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "999000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123...", "fees": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": null, "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", "finalized_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:30:00.000Z", "expires_at": "2024-03-02T10: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": "0xdeadbeef..." } } } } } }, "responses": { "200": { "description": "Signature submitted 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": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "1000000", "to_network": "ETHEREUM", "to_currency": "USDC", "risk_status": "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", "transfer_id": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e", "from_amount": "1000000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e", "to_amount": "999000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123...", "fees": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "provider_key": null, "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", "finalized_at": null, "failed_at": null } ], "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:30:00.000Z", "expires_at": "2024-03-02T10: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/ramps/deposits": { "get": { "operationId": "ramps_getDeposits", "parameters": [ { "name": "depositAddress", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposits retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get all deposits (onramp transactions) with optional depositAddress filter", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/offramp": { "post": { "operationId": "ramps_createOfframpTransaction", "parameters": [], "responses": { "201": { "description": "Offramp transaction created successfully" }, "400": { "description": "Invalid request data" }, "401": { "description": "KYB not completed" } }, "security": [ { "bearer": [] } ], "summary": "Create offramp transaction", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/offramp/external/{externalId}": { "get": { "operationId": "ramps_getOfframpByExternalId", "parameters": [ { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offramp transaction retrieved successfully" }, "404": { "description": "Offramp transaction not found" } }, "security": [ { "bearer": [] } ], "summary": "Get offramp by externalId", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/offramp/quote": { "post": { "operationId": "ramps_createOfframpQuote", "parameters": [], "responses": { "200": { "description": "Quote retrieved successfully" }, "400": { "description": "Invalid request data" } }, "security": [ { "bearer": [] } ], "summary": "Get offramp quote", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/offramp/{id}": { "get": { "operationId": "ramps_getOfframpById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offramp transaction retrieved successfully" }, "404": { "description": "Offramp transaction not found" } }, "security": [ { "bearer": [] } ], "summary": "Get specific offramp by ID", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/offramp/{id}/submit": { "post": { "description": "Submit a previously created offramp transaction by providing the signed transaction. This endpoint:\n\n- Validates the signed transaction matches the offramp transaction details\n- Submits the transaction to the blockchain\n- Updates the offramp transaction status with the tx hash\n- Triggers status progression (in development mode)", "operationId": "ramps_submitOfframpTransaction", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction submitted successfully" }, "400": { "description": "Invalid request or validation failed" }, "404": { "description": "Offramp transaction not found" } }, "security": [ { "bearer": [] } ], "summary": "Submit signed offramp transaction to blockchain", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/onramp": { "post": { "operationId": "ramps_createOnrampTransaction", "parameters": [], "responses": { "201": { "description": "Onramp transaction created successfully" }, "400": { "description": "Invalid request data" }, "401": { "description": "KYB not completed" } }, "security": [ { "bearer": [] } ], "summary": "Create onramp transaction", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/onramp/external/{externalId}": { "get": { "operationId": "ramps_getOnrampByExternalId", "parameters": [ { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Onramp transaction retrieved successfully" }, "404": { "description": "Onramp transaction not found" } }, "security": [ { "bearer": [] } ], "summary": "Get onramp by externalId", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/onramp/quote": { "post": { "operationId": "ramps_createOnrampQuote", "parameters": [], "responses": { "200": { "description": "Quote retrieved successfully" }, "400": { "description": "Invalid request data" } }, "security": [ { "bearer": [] } ], "summary": "Get onramp quote", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/onramp/{id}": { "get": { "operationId": "ramps_getOnrampById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Onramp transaction retrieved successfully" }, "404": { "description": "Onramp transaction not found" } }, "security": [ { "bearer": [] } ], "summary": "Get specific onramp by ID", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-inbound"] } } } }, "/v1/ramps/withdraws": { "get": { "operationId": "ramps_getWithdraws", "parameters": [ { "name": "originAddress", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdraws retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "Get all withdraws (offramp transactions) with optional originAddress filter", "tags": ["ramps"], "x-internal": true, "x-zuplo-route": { "corsPolicy": "anything-goes", "handler": { "export": "mockHandler", "module": "$import(./modules/mock-handler)" }, "policies": { "inbound": ["auth0-jwt-auth-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": "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": "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", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 0, "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, "finalized_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "swap", "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, "finalized_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 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": "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 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", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 0, "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, "finalized_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "swap", "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, "finalized_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", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 0, "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, "finalized_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "transfer_id": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e", "step_sequence": 1, "step_type": "swap", "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, "finalized_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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "balance_status": null, "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" } ], "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- `from_network` / `to_network` are required for wallet accounts and disallowed for ledger accounts.\n- When `from_currency`/`to_currency` and `from_network`/`to_network` are the same, both `from_amount` and `to_amount` may be provided. When they differ, only one amount is allowed.", "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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC" } } } } } }, "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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "balance_status": null, "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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "7d3e1a9f-2c4b-4f85-b0a6-8e5c2d1f3b9a", "transfer_id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": null, "fees": [], "provider_key": "circle_mint", "status": "finalized", "status_reasons": null, "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", "finalized_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 signed on-chain transaction for a wallet-to-wallet rebalance step prepared by the Turnkey provider. The backend validates the signed transaction against the step's destination + amount, then broadcasts it on-chain.\n\nOnly steps where `provider_key` is `turnkey` and status is `created` or `signature_requested` (with an unsigned transaction already prepared) can be signed.", "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 accepted and submitted on-chain", "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", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "balance_status": "reserved", "balance_reserved_at": "2024-03-01T10:00:00.000Z", "steps": [ { "id": "7d3e1a9f-2c4b-4f85-b0a6-8e5c2d1f3b9a", "transfer_id": "e4a1b7c3-9f2d-4e56-a8b0-3c5d1e7f9a2b", "step_sequence": 1, "step_type": "transfer", "from_account_id": "6de8a7e9-be79-4885-9b65-b25b11d38078", "from_amount": "1000", "from_network": "ETHEREUM", "from_currency": "USDC", "to_account_id": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889", "to_amount": "1000", "to_network": "ETHEREUM", "to_currency": "USDC", "transaction_hash": "0xabc123", "fees": [], "provider_key": "turnkey", "status": "submitted", "status_reasons": null, "created_at": "2024-03-01T10:00:00.000Z", "updated_at": "2024-03-01T10:00:10.000Z", "submitted_at": "2024-03-01T10:00:10.000Z", "confirmed_at": null, "finalized_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-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": "Submit signed on-chain 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": { "post": { "description": "Create a withdrawal payment.", "operationId": "treasury_createWithdrawal", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalRequest" }, "examples": { "default": { "summary": "Create withdrawal", "value": { "from_account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "from_amount": "1000", "from_currency": "USDC", "to_account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "to_currency": "USD" } } } } } }, "responses": { "201": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "data": { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "funding_account_id": null, "from_account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "from_amount": "1000", "from_network": null, "from_currency": "USDC", "to_account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "to_amount": null, "to_network": null, "to_currency": "USD", "risk_status": null, "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": null, "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" } ] } } } } } }, "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 payment 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/PaymentResponse" }, "examples": { "circle": { "summary": "Circle provider withdrawal", "value": { "data": { "id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "workspace_id": "b53f6690-3242-4942-9907-885779632832", "organization_reference_id": null, "direction": "outbound", "funding_account_id": null, "from_account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "from_amount": "1000", "from_network": null, "from_currency": "USDC", "to_account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "to_amount": "1000", "to_network": null, "to_currency": "USD", "risk_status": null, "risk_status_reasons": [], "risk_reviewed_by": null, "risk_reviewed_at": null, "balance_status": null, "balance_reserved_at": null, "steps": [ { "id": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a", "transfer_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 1, "step_type": "transfer", "from_account_id": "55042f8f-e527-56f1-b57c-eef23ca862db", "from_amount": "1000", "from_network": null, "from_currency": "USDC", "to_account_id": "00000000-0000-0000-0001-744269e65952", "to_amount": "1000", "to_network": null, "to_currency": "USDC", "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, "finalized_at": null, "completed_at": null, "failed_at": null }, { "id": "3b7e9d2f-1c4a-4f68-a5b0-6e8c1d3f9a2b", "transfer_id": "6a2f8c1e-3b9d-4e74-b5a0-7c4d2e1f9b3a", "step_sequence": 2, "step_type": "transfer", "from_account_id": "b72de3f5-8a1c-4b39-c06e-4f9d1a2e7b3c", "from_amount": "1000", "from_network": null, "from_currency": "USD", "to_account_id": "44031e7e-d416-45f0-a46b-ded12b9751ca", "to_amount": "1000", "to_network": null, "to_currency": "USD", "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, "finalized_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" } } } } } } } }, "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/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" } ] } } } } } }, "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/alfred": { "post": { "operationId": "webhook_receiveAlfredWebhook", "parameters": [ { "name": "signature", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "bypass-sig-verification", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "400": { "description": "Invalid webhook payload" }, "401": { "description": "Invalid webhook signature" } }, "summary": "Receive webhook updates from Alfred Pay", "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": [] } }, "/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": [] } }, "/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": [] } }, "/v1/webhooks/openfx": { "post": { "operationId": "webhook_receiveOpenFxWebhook", "parameters": [ { "name": "x-openfx-signature", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "401": { "description": "Invalid webhook signature" } }, "summary": "Receive webhook notifications from OpenFX", "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": [] } }, "/v1/webhooks/quicknode/{network}": { "post": { "operationId": "webhook_receiveQuicknodeWebhookForNetwork", "parameters": [ { "name": "network", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook processed successfully" }, "400": { "description": "Invalid webhook payload" } }, "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": [] } }, "/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_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_createWithdrawal" }, { "file": "./config/routes.oas.json", "id": "treasury_getWithdrawal" } ] } }, "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 }, "beneficiary_name": { "type": "string", "minLength": 1, "description": "Beneficiary name registered with the provider (required when provider=OPENFX).", "example": "Acme Corp" }, "provider": { "type": "string", "enum": ["CIRCLE_MINT", "OPENFX"] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" } }, "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"] }, "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"] }, "ListOrgUsersResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": ["owner", "admin", "operator", "compliance", "viewer"] }, "status": { "type": "string", "enum": ["active", "pending", "inactive"] }, "lastActiveAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "firstName", "lastName", "role", "status", "lastActiveAt", "createdAt", "updatedAt" ] } } }, "required": ["message", "data"] }, "OrgUserDto": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": ["owner", "admin", "operator", "compliance", "viewer"] }, "status": { "type": "string", "enum": ["active", "pending", "inactive"] }, "lastActiveAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "firstName", "lastName", "role", "status", "lastActiveAt", "createdAt", "updatedAt" ] }, "CreateUserRequestDto": { "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,}$" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "role": { "default": "viewer", "type": "string", "enum": ["owner", "admin", "operator", "compliance", "viewer"] } }, "required": ["email", "firstName", "lastName"] }, "CreateUserResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "operator", "compliance", "viewer" ] }, "status": { "type": "string", "enum": ["active", "pending", "inactive"] }, "lastActiveAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "firstName", "lastName", "role", "status", "lastActiveAt", "createdAt", "updatedAt" ] } }, "required": ["user"] } }, "required": ["message", "data"] }, "UpdateUserRequestDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "role": { "type": "string", "enum": ["owner", "admin", "operator", "compliance", "viewer"] }, "status": { "type": "string", "enum": ["active", "pending", "inactive"] } } }, "UpdateUserResponseDto": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "operator", "compliance", "viewer" ] }, "status": { "type": "string", "enum": ["active", "pending", "inactive"] }, "lastActiveAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "firstName", "lastName", "role", "status", "lastActiveAt", "createdAt", "updatedAt" ] } }, "required": ["user"] } }, "required": ["message", "data"] }, "UpdateRiskProfileRequest": { "type": "object", "properties": { "riskProfile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "The risk profile for compliance screening" } }, "required": ["riskProfile"] }, "UpdateRiskProfileResponse": { "type": "object", "properties": { "riskProfile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "New risk profile" }, "oldRiskProfile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "Previous risk profile" }, "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))$", "description": "Timestamp of the update" } }, "required": ["riskProfile", "oldRiskProfile", "updatedAt"] }, "RiskProfileResponse": { "type": "object", "properties": { "riskProfile": { "type": "string", "enum": ["conservative", "balanced", "aggressive"], "description": "Current risk profile" } }, "required": ["riskProfile"] }, "CreateSecretRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": ["CIRCLE_MINT", "OPENFX"], "description": "The secret provider (CIRCLE_MINT or OPENFX)" }, "key": { "type": "string", "enum": ["CIRCLE_MINT_API_KEY", "OPENFX_CREDENTIALS"], "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)" }, { "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" }, "maskedValue": { "type": "string", "description": "Masked version of the stored secret (e.g., '****abc123')" } }, "required": ["success", "maskedValue"] }, "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"] }, "PaymentFee": { "type": "object", "properties": { "fee_amount": { "type": "string", "description": "Fee amount in smallest currency units", "example": "1000" }, "fee_currency": { "type": "string", "description": "Currency code for the fee", "example": "USDC" }, "fee_type": { "type": "string", "description": "Type of fee (e.g., 'gas', 'service')", "example": "gas" }, "fee_metadata": { "type": "object", "description": "Additional metadata about the fee", "nullable": true, "additionalProperties": true, "example": {} } }, "required": ["fee_amount", "fee_currency", "fee_type"] }, "PaymentStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "transfer_id": { "type": "string", "description": "ID of the parent payment/transfer", "example": "5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e" }, "step_sequence": { "type": "integer", "description": "Order of this step in the payment flow", "example": 1 }, "step_type": { "type": "string", "description": "Type of step", "enum": ["transfer", "swap"], "example": "transfer" }, "from_account_id": { "type": "string", "description": "Source account ID for this step", "nullable": true, "example": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e" }, "from_amount": { "type": "string", "description": "Amount being sent from source", "example": "1000000" }, "from_network": { "type": "string", "description": "Source blockchain network", "nullable": true, "example": "ETHEREUM" }, "from_currency": { "type": "string", "description": "Source currency code", "example": "USDC" }, "to_account_id": { "type": "string", "description": "Destination account ID for this step", "nullable": true, "example": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e" }, "to_amount": { "type": "string", "description": "Amount being received at destination", "example": "999000" }, "to_network": { "type": "string", "description": "Destination blockchain network", "nullable": true, "example": "ETHEREUM" }, "to_currency": { "type": "string", "description": "Destination currency code", "example": "USDC" }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash", "nullable": true, "example": "0xabc123..." }, "fees": { "description": "Fees associated with this step", "example": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "type": "array", "items": { "$ref": "#/components/schemas/PaymentFee" } }, "provider_key": { "type": "string", "description": "Provider used for this step", "nullable": true, "enum": ["alfred", "circle_mint", "turnkey"], "example": null }, "status": { "type": "string", "description": "Current status of this step", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "finalized", "completed", "failed" ], "example": "confirmed" }, "status_reasons": { "description": "Reasons for the current status", "nullable": true, "example": [], "type": "array", "items": { "type": "string" } }, "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": "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" }, "finalized_at": { "type": "string", "description": "Timestamp when step was finalized", "format": "date-time", "nullable": true, "example": null }, "completed_at": { "type": "string", "description": "Timestamp when step was 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", "transfer_id", "step_sequence", "step_type", "from_amount", "from_currency", "to_amount", "to_currency", "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", "nullable": true, "example": "2a8f4c1e-9b3d-4e56-b7a0-5c6d2e1f9b3a" }, "from_account_id": { "type": "string", "description": "Source account ID", "nullable": true, "example": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e" }, "from_amount": { "type": "string", "description": "Amount in source currency", "example": "1000000" }, "from_network": { "type": "string", "description": "Source blockchain network", "nullable": true, "example": "ETHEREUM" }, "from_currency": { "type": "string", "description": "Source currency code", "example": "USDC" }, "to_account_id": { "type": "string", "description": "Destination account ID", "nullable": true, "example": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e" }, "to_amount": { "type": "string", "description": "Amount in destination currency", "example": "1000000" }, "to_network": { "type": "string", "description": "Destination blockchain network", "nullable": true, "example": "ETHEREUM" }, "to_currency": { "type": "string", "description": "Destination currency code", "example": "USDC" }, "risk_status": { "type": "string", "description": "Risk assessment status", "nullable": true, "enum": [ "unchecked", "awaiting_decision", "auto_approved", "manually_approved", "auto_rejected", "manually_rejected" ], "example": "auto_approved" }, "risk_status_reasons": { "description": "Reasons for risk status", "nullable": true, "example": [], "type": "array", "items": { "type": "string" } }, "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", "reserved", "awaiting_funds"], "example": "reserved" }, "balance_reserved_at": { "type": "string", "description": "Timestamp when balance was reserved", "format": "date-time", "nullable": true, "example": "2024-03-01T09:59:00.000Z" }, "steps": { "description": "Payment execution steps", "type": "array", "items": { "$ref": "#/components/schemas/PaymentStep" } }, "created_at": { "type": "string", "description": "Payment creation timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Payment last update timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "Payment expiration timestamp", "format": "date-time", "example": "2024-03-02T10:00:00.000Z" } }, "required": [ "id", "workspace_id", "direction", "from_amount", "from_currency", "to_amount", "to_currency", "risk_status", "created_at", "updated_at", "expires_at" ] }, "PaymentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["data", "pagination"] }, "PaymentResponse": { "type": "object", "properties": { "data": { "description": "Payment data", "allOf": [ { "$ref": "#/components/schemas/Payment" } ] } }, "required": ["data"] }, "ReviewPaymentRequest": { "type": "object", "properties": { "is_approved": { "type": "boolean", "description": "Approve (true) or reject (false) the payment." } }, "required": ["is_approved"] }, "CreatePaymentRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional external reference ID for the organization." }, "funding_account_id": { "type": "string", "description": "ID of the funding account." }, "from_account_id": { "type": "string", "description": "ID of the source account (e.g., wallet)." }, "from_amount": { "type": "string", "description": "Amount to send in source currency units. Required if to_amount is not provided." }, "from_network": { "type": "string", "description": "Blockchain network for source currency (e.g., 'POLYGON'). See GET /networks for supported values.", "minLength": 1 }, "from_currency": { "type": "string", "description": "Source currency code (e.g., 'USDC'). See GET /currencies for supported values.", "minLength": 1 }, "to_account_id": { "type": "string", "description": "ID of the destination account." }, "to_amount": { "type": "string", "description": "Amount to receive in destination currency units. Required if from_amount is not provided." }, "to_network": { "type": "string", "description": "Blockchain network for destination currency (if applicable). See GET /networks for supported values.", "minLength": 1 }, "to_currency": { "type": "string", "description": "Destination currency code (e.g., 'USD'). See GET /currencies for supported values.", "minLength": 1 } }, "required": ["from_currency", "to_currency"] }, "UpdatePaymentRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional external reference ID to update." }, "funding_account_id": { "type": "string", "description": "ID of the funding account." }, "from_account_id": { "type": "string", "description": "ID of the source account (e.g., wallet)." }, "to_account_id": { "type": "string", "description": "ID of the destination account." } }, "required": ["funding_account_id", "from_account_id", "to_account_id"] }, "SignPaymentStepRequest": { "type": "object", "properties": { "signature": { "type": "string", "description": "The signed transaction or message." } }, "required": ["signature"] }, "CreateWithdrawalRequest": { "type": "object", "properties": { "from_currency": { "type": "string", "description": "Source currency code." }, "to_currency": { "type": "string", "description": "Destination currency code." }, "from_amount": { "type": "string", "description": "Amount to send." }, "from_account_id": { "type": "string", "description": "Source account ID." }, "to_account_id": { "type": "string", "description": "Destination account ID." }, "from_network": { "description": "Network for the withdrawal.", "type": "string" }, "to_network": { "description": "Network for the destination.", "type": "string" } }, "required": [ "from_currency", "to_currency", "from_amount", "from_account_id", "to_account_id" ] }, "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"] }, "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"] }, "DepositStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the step.", "example": "8a4f2c1e-9b6d-4e35-b7a0-3c5d1e9f2b8a" }, "transfer_id": { "type": "string", "description": "ID of the parent payment/transfer.", "example": "1c8e4a6f-9b2d-4f53-a0e7-5d3c1b9f2a8e" }, "step_sequence": { "type": "integer", "description": "Step sequence number (0-based).", "example": 0 }, "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": ["alfred", "circle_mint", "turnkey"], "example": "circle_mint", "nullable": true }, "status": { "type": "string", "description": "Step status: 'created', 'signature_requested', 'signed', 'submitted', 'confirmed', 'finalized', 'completed', 'failed'.", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "finalized", "completed", "failed" ], "example": "created" }, "status_reasons": { "description": "Array of reasons explaining the current status (if any).", "example": null, "nullable": true, "type": "array", "items": { "type": "string" } }, "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 }, "finalized_at": { "type": "string", "description": "Finalized 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", "transfer_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." }, "business_state": { "type": "string", "description": "State." }, "business_postal_code": { "type": "string", "description": "Postal code." }, "business_country": { "type": "string", "description": "Country code." } }, "required": [ "business_legal_name", "business_city", "business_state", "business_postal_code", "business_country" ] }, "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." }, "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", "bank_swift_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"] }, "RebalanceStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique step identifier", "example": "4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a" }, "transfer_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", "example": 1 }, "step_type": { "type": "string", "description": "Type of step", "enum": ["transfer", "swap"], "example": "transfer" }, "from_account_id": { "type": "string", "description": "Source account ID for this step", "nullable": true, "example": "6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e" }, "from_amount": { "type": "string", "description": "Amount being sent from source", "example": "1000" }, "from_network": { "type": "string", "description": "Source blockchain network", "nullable": true, "example": "ETHEREUM" }, "from_currency": { "type": "string", "description": "Source currency code", "example": "USDC" }, "to_account_id": { "type": "string", "description": "Destination account ID for this step", "nullable": true, "example": "8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e" }, "to_amount": { "type": "string", "description": "Amount being received at destination", "example": "1000" }, "to_network": { "type": "string", "description": "Destination blockchain network", "nullable": true, "example": "ETHEREUM" }, "to_currency": { "type": "string", "description": "Destination currency code", "example": "USDC" }, "transaction_hash": { "type": "string", "description": "Blockchain transaction hash", "nullable": true, "example": "0xabc123..." }, "fees": { "description": "Fees associated with this step", "example": [ { "fee_amount": "1000", "fee_currency": "USDC", "fee_type": "gas", "fee_metadata": {} } ], "type": "array", "items": { "$ref": "#/components/schemas/StepFee" } }, "provider_key": { "type": "string", "description": "Provider used for this step", "nullable": true, "enum": ["alfred", "circle_mint", "turnkey"], "example": null }, "unsigned_transaction": { "type": "string", "description": "Serialized unsigned ERC-20 transfer ready to be signed client-side via Turnkey. Only populated for provider_key = turnkey while the step is awaiting a signature.", "nullable": true }, "status": { "type": "string", "description": "Current status of this step", "enum": [ "created", "signature_requested", "signed", "submitted", "confirmed", "finalized", "completed", "failed" ], "example": "confirmed" }, "status_reasons": { "description": "Reasons for the current status", "nullable": true, "example": [], "type": "array", "items": { "type": "string" } }, "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": "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" }, "finalized_at": { "type": "string", "description": "Timestamp when step was finalized", "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", "transfer_id", "step_sequence", "step_type", "from_amount", "from_currency", "to_amount", "to_currency", "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": "ref_123" }, "direction": { "type": "string", "description": "Payment direction", "enum": ["rebalance"], "example": "rebalance" }, "from_account_id": { "type": "string", "description": "Source account ID", "example": "6de8a7e9-be79-4885-9b65-b25b11d38078" }, "from_amount": { "type": "string", "description": "Amount in source currency", "example": "1000" }, "from_network": { "type": "string", "description": "Source blockchain network", "nullable": true, "example": "ETHEREUM" }, "from_currency": { "type": "string", "description": "Source currency code", "example": "USDC" }, "to_account_id": { "type": "string", "description": "Destination account ID", "example": "53b7aabd-97bc-4a4f-9f9c-1c1c69474889" }, "to_amount": { "type": "string", "description": "Amount in destination currency", "example": "1000" }, "to_network": { "type": "string", "description": "Destination blockchain network", "nullable": true, "example": "ETHEREUM" }, "to_currency": { "type": "string", "description": "Destination currency code", "example": "USDC" }, "balance_status": { "type": "string", "description": "Balance reservation status", "nullable": true, "enum": ["unreserved", "awaiting_funds", "reserved"], "example": "reserved" }, "balance_reserved_at": { "type": "string", "description": "Timestamp when balance was reserved", "format": "date-time", "nullable": true, "example": "2024-03-01T09:59:00.000Z" }, "steps": { "description": "Rebalance execution steps", "type": "array", "items": { "$ref": "#/components/schemas/RebalanceStep" } }, "created_at": { "type": "string", "description": "Rebalance creation timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Rebalance last update timestamp", "format": "date-time", "example": "2024-03-01T10:00:00.000Z" }, "expires_at": { "type": "string", "description": "Rebalance expiration timestamp", "format": "date-time", "example": "2024-03-04T10:00:00.000Z" } }, "required": [ "id", "workspace_id", "direction", "from_account_id", "from_amount", "from_currency", "to_account_id", "to_amount", "to_currency", "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"] }, "CreateRebalanceRequest": { "type": "object", "properties": { "organization_reference_id": { "type": "string", "description": "Optional reference ID for the rebalance." }, "from_account_id": { "type": "string", "description": "Source account ID." }, "from_amount": { "type": "string", "description": "Amount to send from the source account." }, "from_network": { "type": "string", "description": "Network for the source account." }, "from_currency": { "type": "string", "description": "Source currency code." }, "to_account_id": { "type": "string", "description": "Destination account ID." }, "to_amount": { "type": "string", "description": "Amount to receive at the destination account." }, "to_network": { "type": "string", "description": "Network for the destination account." }, "to_currency": { "type": "string", "description": "Destination currency code." } }, "required": [ "from_account_id", "from_currency", "to_account_id", "to_currency" ] }, "SignRebalanceStepRequest": { "type": "object", "properties": { "signature": { "type": "string", "minLength": 1, "description": "The signed transaction or message.", "example": "0xdeadbeef..." } }, "required": ["signature"] } } }, "security": [ { "bearer": [] } ] }