{ "openapi": "3.1.0", "info": { "title": "Valtu Wallet API", "version": "1.0.0", "description": "Server-to-server API for Valtu Wallet. Every request is signed with your API key (see https://valtu.io/docs/api#authentication). Amounts are integer strings in base units." }, "servers": [ { "url": "https://valtu.io/v1" } ], "security": [ { "ValtuSignature": [] } ], "components": { "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable error code, e.g. NO_GAS" }, "message": { "type": "string", "description": "For people" } }, "required": [ "code", "message" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "PENDING_REVIEW", "ACTIVATING", "ACTIVE", "SUSPENDED", "REJECTED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "activatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "slug", "environment", "status", "createdAt", "activatedAt" ] }, "WalletAddress": { "type": "object", "properties": { "addressFormat": { "type": "string", "description": "e.g. ADDRESS_FORMAT_TRON" }, "address": { "type": "string" }, "networks": { "type": "array", "items": { "type": "string", "description": "Network key, e.g. tron" } } }, "required": [ "addressFormat", "address", "networks" ] }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "operational", "treasury" ] }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalGroupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "description": "Set while the wallet is frozen", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAddress" } } }, "required": [ "id", "name", "type", "externalId", "approvalGroupId", "disabledAt", "createdAt", "addresses" ] }, "WalletBalance": { "type": "object", "properties": { "asset": { "type": "string" }, "chain": { "type": "string" }, "address": { "type": "string" }, "decimals": { "type": "integer" }, "balance": { "anyOf": [ { "type": "string", "description": "On-chain balance; null if the network couldn't be read", "pattern": "^[0-9]+$" }, { "type": "null" } ] }, "onHold": { "type": "string", "description": "Reserved by payouts not yet sent", "pattern": "^[0-9]+$" }, "available": { "anyOf": [ { "type": "string", "description": "balance − onHold", "pattern": "^[0-9]+$" }, { "type": "null" } ] }, "usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "closesAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "error": { "type": "string", "description": "Why the balance couldn't be read" } }, "required": [ "asset", "chain", "address", "decimals", "balance", "onHold", "available", "usd", "closesAt" ] }, "WalletBalances": { "type": "object", "properties": { "walletId": { "type": "string", "format": "uuid" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/WalletBalance" } }, "totalUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "walletId", "balances", "totalUsd" ] }, "BalanceSummary": { "type": "object", "properties": { "asset": { "type": "string" }, "chain": { "type": "string" }, "decimals": { "type": "integer" }, "usdPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "held": { "anyOf": [ { "type": "object", "properties": { "balance": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "wallets": { "type": "integer" } }, "required": [ "balance", "usd", "wallets" ] }, { "type": "null" } ] }, "awaitingSweep": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "wallets": { "type": "integer" } }, "required": [ "amount", "usd", "wallets" ] }, { "type": "null" } ] }, "closesAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "asset", "chain", "decimals", "usdPrice", "held", "awaitingSweep", "closesAt" ] }, "Network": { "type": "object", "properties": { "chain": { "type": "string" }, "name": { "type": "string" }, "nativeAsset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "operational", "degraded", "down", "unknown" ] }, "deposits": { "type": "boolean", "description": "Deposits are being watched" }, "sends": { "type": "boolean", "description": "Payouts can be sent" }, "closing": { "anyOf": [ { "type": "object", "properties": { "closesAt": { "type": "string", "format": "date-time" }, "notice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "closesAt", "notice" ] }, { "type": "null" } ] }, "typicalConfirmSeconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "typicalFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "chain", "name", "nativeAsset", "status", "deposits", "sends", "closing", "typicalConfirmSeconds", "typicalFeeUsd" ] }, "Transfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "TRANSFER", "SWEEP", "GAS", "CALL" ] }, "walletId": { "type": "string", "format": "uuid" }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "chain": { "type": "string" }, "asset": { "type": "string" }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "amount": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "to": { "type": "string" }, "addressBookId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "addressLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING_APPROVAL", "QUEUED", "SIGNING", "AWAITING_OFFICER", "BROADCAST", "CONFIRMED", "FAILED", "REJECTED", "CANCELLED", "NEEDS_REVIEW" ] }, "requiredApprovals": { "type": "integer" }, "approvalGroupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "approvalGroupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policyReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "proposedBy": { "type": "string" }, "proposerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proposerAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "txHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "networkFee": { "anyOf": [ { "type": "string", "description": "Fee paid, base units of feeAsset", "pattern": "^[0-9]+$" }, { "type": "null" } ] }, "feeAsset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "feeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "confirmations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "failure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string", "description": "Why it is waiting" }, { "type": "null" } ] }, "waitingSince": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "call": { "anyOf": [ { "type": "object", "properties": { "contractId": { "type": "string", "format": "uuid" }, "contractLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "function": { "type": "string" }, "signature": { "type": "string" }, "selector": { "type": "string", "description": "4-byte selector, hex" }, "args": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "value": {} }, "required": [ "name", "type", "value" ] } }, "data": { "type": "string", "description": "Calldata, 0x-hex" } }, "required": [ "contractId", "contractLabel", "function", "signature", "selector", "args", "data" ] }, { "type": "null" } ] } }, "required": [ "id", "kind", "walletId", "chain", "asset", "amount", "to", "status", "createdAt" ] }, "MessageRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "walletId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "eip191", "eip712", "tip191", "solana" ] }, "address": { "type": "string", "description": "The signing address" }, "message": { "type": "object", "properties": { "text": { "type": "string" }, "hex": { "type": "string" }, "typedData": { "type": "object" } }, "required": [] }, "status": { "type": "string", "enum": [ "PENDING_APPROVAL", "SIGNED", "REJECTED", "EXPIRED", "FAILED" ] }, "approvals": { "type": "object", "properties": { "required": { "type": "integer" }, "count": { "type": "integer" }, "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "required", "count", "accountIds" ] }, "signature": { "anyOf": [ { "type": "string", "description": "EVM/TRON: 0x r||s||v (65 bytes, v 27/28). Solana: base58" }, { "type": "null" } ] }, "signatureHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "walletId", "type", "address", "message", "status", "approvals", "signature", "signatureHex", "error", "externalId", "note", "createdAt", "expiresAt", "decidedAt" ] }, "Contract": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "address": { "type": "string" }, "label": { "type": "string" }, "functions": { "type": "array", "items": { "type": "string", "description": "Allowed function signature" } }, "allFunctions": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "chain", "address", "label", "functions", "allFunctions", "createdAt" ] }, "FeeQuote": { "type": "object", "properties": { "asset": { "type": "string", "description": "The network's own coin" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "fee": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payer": { "type": "string", "enum": [ "wallet", "gas_station" ] }, "ok": { "type": "boolean" }, "code": { "anyOf": [ { "type": "string", "enum": [ "NO_GAS", "INSUFFICIENT_FOR_FEE" ] }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSendable": { "type": "string", "description": "Native coin only: the most that can be sent with the fee paid", "pattern": "^[0-9]+$" } }, "required": [ "asset", "symbol", "decimals", "fee", "usd", "payer", "ok", "code", "message" ] }, "TransferPreview": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DEFAULT", "DENY" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvals": { "type": "integer" }, "groupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "othersNeeded": { "type": "integer" }, "usdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fee": { "anyOf": [ { "$ref": "#/components/schemas/FeeQuote" }, { "type": "null" } ] } }, "required": [ "outcome", "reason", "approvals", "groupName", "usdValue", "fee" ] }, "BatchResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "externalId": { "type": "string" }, "ok": { "type": "boolean" }, "transfer": { "$ref": "#/components/schemas/Transfer" }, "error": { "type": "object", "properties": { "status": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "code", "message" ] } }, "required": [ "index", "ok" ] } }, "created": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "results", "created", "failed" ] }, "Deposit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "walletId": { "type": "string", "format": "uuid" }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "walletExternalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "chain": { "type": "string" }, "asset": { "type": "string" }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "amount": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "usdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "address": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "txHash": { "type": "string" }, "outputIndex": { "type": "integer" }, "blockNumber": { "type": "string" }, "confirmations": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "ORPHANED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "walletId", "chain", "asset", "amount", "address", "txHash", "status", "createdAt" ] }, "DepositLookupResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "found", "not_found", "pending", "rescanning" ] }, "deposits": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" } }, "block": { "type": "string" }, "rescanId": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "required": [ "status" ] }, "Asset": { "type": "object", "properties": { "asset": { "type": "string", "description": "e.g. USDT-TRC20" }, "chain": { "type": "string" }, "network": { "type": "string", "enum": [ "mainnet", "testnet" ] }, "addressFormat": { "type": "string" }, "decimals": { "type": "integer" }, "contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closesAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "asset", "chain", "network", "addressFormat", "decimals", "contract", "closesAt" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "pausedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastSuccessAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "pending": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "id", "url", "description", "events", "createdAt", "pausedAt", "lastSuccessAt", "lastFailureAt", "pending", "failed" ] }, "WebhookPublicKey": { "type": "object", "properties": { "algorithm": { "type": "string", "const": "Ed25519" }, "publicKey": { "type": "string", "description": "base64url raw key" }, "pem": { "type": "string" } }, "required": [ "algorithm", "publicKey", "pem" ] }, "Checkout": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "description": "Hosted payment page: send the payer here" }, "status": { "type": "string", "enum": [ "OPEN", "PROCESSING", "COMPLETED", "UNDERPAID", "EXPIRED", "CANCELLED" ] }, "amount": { "type": "string", "description": "USD, 2 decimals" }, "currency": { "type": "string", "const": "USD" }, "assets": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ] }, "successUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "walletId": { "type": "string", "format": "uuid" }, "quote": { "anyOf": [ { "type": "object", "properties": { "asset": { "type": "string" }, "chain": { "type": "string" }, "amount": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "decimals": { "type": "integer" }, "address": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "asset", "chain", "amount", "decimals", "address", "expiresAt" ] }, { "type": "null" } ] }, "received": { "type": "string", "description": "Confirmed, in the quoted coin", "pattern": "^[0-9]+$" }, "pending": { "type": "string", "description": "Integer string in base units", "pattern": "^[0-9]+$" }, "depositIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "paidLate": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "status", "amount", "currency", "assets", "description", "externalId", "metadata", "successUrl", "cancelUrl", "walletId", "quote", "received", "pending", "depositIds", "paidLate", "expiresAt", "completedAt", "createdAt" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "De-duplicate on this", "format": "uuid" }, "type": { "type": "string", "description": "e.g. deposit.confirmed" }, "workspaceId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "type", "workspaceId", "createdAt", "data" ] } }, "securitySchemes": { "ValtuSignature": { "type": "apiKey", "in": "header", "name": "X-Stamp", "description": "ECDSA P-256 signature over METHOD\\npath?query\\ntimestampMs\\nnonce\\nhex(sha256(body)), sent with X-Valtu-Timestamp and X-Valtu-Nonce. Use @valtu/wallet-kit or see the docs." } } }, "paths": { "/workspace": { "get": { "summary": "The key's workspace", "description": "Minimum key role: `read`.", "operationId": "getWorkspace", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallets": { "post": { "summary": "Create a wallet (idempotent by externalId)", "description": "Minimum key role: `operate`.", "operationId": "createWallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "type": { "type": "string", "enum": [ "treasury", "operational", "user" ] }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List wallets", "description": "Minimum key role: `read`.", "operationId": "listWallets", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "treasury", "operational", "user" ] } }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "wallets", "nextCursor" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallets/{id}": { "get": { "summary": "Get a wallet", "description": "Minimum key role: `read`.", "operationId": "getWallet", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallets/{id}/balances": { "get": { "summary": "Live balances of a wallet", "description": "Minimum key role: `read`.", "operationId": "getWalletBalances", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalances" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balances": { "get": { "summary": "Workspace totals per coin", "description": "Minimum key role: `read`.", "operationId": "getBalances", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "balances": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceSummary" } } }, "required": [ "balances" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/networks": { "get": { "summary": "Network status, typical confirmation time and fee", "description": "Minimum key role: `read`.", "operationId": "listNetworks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "networks": { "type": "array", "items": { "$ref": "#/components/schemas/Network" } } }, "required": [ "networks" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transfers": { "post": { "summary": "Send a payout (idempotent by externalId)", "description": "Minimum key role: `operate`.", "operationId": "createTransfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "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)$" }, "asset": { "type": "string", "minLength": 1, "maxLength": 32 }, "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "to": { "type": "string", "minLength": 10, "maxLength": 128 }, "addressBookId": { "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)$" }, "note": { "type": "string", "maxLength": 500 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "walletId", "asset", "amount" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/Transfer" } }, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List transfers", "description": "Minimum key role: `read`.", "operationId": "listTransfers", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z_]{2,32}(,[A-Z_]{2,32}){0,15}$" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z_]{2,32}(,[A-Z_]{2,32}){0,15}$" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 32 } }, { "name": "after", "in": "query", "required": false, "schema": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "walletId", "in": "query", "required": false, "schema": { "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": "externalId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "before", "in": "query", "required": false, "schema": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "transfers", "nextCursor" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transfers/preview": { "post": { "summary": "What a payout would do: fee, value, policy outcome (nothing created)", "description": "Minimum key role: `read`.", "operationId": "previewTransfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "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)$" }, "asset": { "type": "string", "minLength": 1, "maxLength": 32 }, "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "to": { "type": "string", "minLength": 10, "maxLength": 128 }, "addressBookId": { "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)$" }, "note": { "type": "string", "maxLength": 500 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "walletId", "asset", "amount" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "$ref": "#/components/schemas/TransferPreview" } }, "required": [ "preview" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transfers/batch": { "post": { "summary": "Up to 100 payouts, each with an externalId; not atomic", "description": "Minimum key role: `operate`.", "operationId": "createTransferBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "walletId": { "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)$" }, "asset": { "type": "string", "minLength": 1, "maxLength": 32 }, "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "to": { "type": "string", "minLength": 10, "maxLength": 128 }, "addressBookId": { "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)$" }, "note": { "type": "string", "maxLength": 500 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "walletId", "asset", "amount" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "transfers" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transfers/{id}": { "get": { "summary": "Get a transfer", "description": "Minimum key role: `read`.", "operationId": "getTransfer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/Transfer" } }, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transfers/{id}/cancel": { "post": { "summary": "Cancel before signing", "description": "Minimum key role: `operate`.", "operationId": "cancelTransfer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/Transfer" } }, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deposits": { "get": { "summary": "List deposits", "description": "Minimum key role: `read`.", "operationId": "listDeposits", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z_]{2,32}(,[A-Z_]{2,32}){0,15}$" } }, { "name": "walletId", "in": "query", "required": false, "schema": { "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": "before", "in": "query", "required": false, "schema": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "after", "in": "query", "required": false, "schema": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 32 } }, { "name": "txHash", "in": "query", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deposits": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "deposits", "nextCursor" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deposits/lookup": { "post": { "summary": "Find a deposit by transaction hash; re-read its block if missed", "description": "Minimum key role: `read`.", "operationId": "lookupDeposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32 }, "txHash": { "type": "string", "pattern": "^(0x)?[0-9a-zA-Z]{32,128}$" } }, "required": [ "chain", "txHash" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositLookupResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deposits/{id}": { "get": { "summary": "Get a deposit", "description": "Minimum key role: `read`.", "operationId": "getDeposit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Deposit id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deposit": { "$ref": "#/components/schemas/Deposit" } }, "required": [ "deposit" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets": { "get": { "summary": "Coins this workspace can use", "description": "Minimum key role: `read`.", "operationId": "listAssets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "required": [ "assets" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkouts": { "post": { "summary": "Create a checkout (payment link); idempotent by externalId", "description": "Minimum key role: `operate`.", "operationId": "createCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": [ "string", "number" ] }, "currency": { "default": "USD", "type": "string", "const": "USD" }, "assets": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "description": { "type": "string", "maxLength": 500 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "successUrl": { "type": "string", "maxLength": 500, "format": "uri" }, "cancelUrl": { "type": "string", "maxLength": 500, "format": "uri" }, "expiresInSeconds": { "default": 3600, "type": "integer", "minimum": 300, "maximum": 604800 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "$ref": "#/components/schemas/Checkout" } }, "required": [ "checkout" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List checkouts", "description": "Minimum key role: `read`.", "operationId": "listCheckouts", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z_]{2,32}(,[A-Z_]{2,32}){0,7}$" } }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkouts": { "type": "array", "items": { "$ref": "#/components/schemas/Checkout" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "checkouts", "nextCursor" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkouts/{id}": { "get": { "summary": "Get a checkout", "description": "Minimum key role: `read`.", "operationId": "getCheckout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Checkout id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "$ref": "#/components/schemas/Checkout" } }, "required": [ "checkout" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkouts/{id}/cancel": { "post": { "summary": "Cancel an open checkout with no payment", "description": "Minimum key role: `operate`.", "operationId": "cancelCheckout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Checkout id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "$ref": "#/components/schemas/Checkout" } }, "required": [ "checkout" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contracts": { "get": { "summary": "Contracts on your allowlist (changed in the dashboard, with approval)", "description": "Minimum key role: `read`.", "operationId": "listContracts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } }, "required": [ "contracts" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contracts/{id}": { "get": { "summary": "A contract and the ABI of its allowed functions", "description": "Minimum key role: `read`.", "operationId": "getContract", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contract id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "contract": { "allOf": [ { "$ref": "#/components/schemas/Contract" }, { "type": "object", "properties": { "abi": { "type": "array", "items": { "type": "object" } } }, "required": [ "abi" ] } ] } }, "required": [ "contract" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contract-calls": { "post": { "summary": "Call an allowed function of an allowlisted contract (a transfer of kind CALL)", "description": "Minimum key role: `operate`.", "operationId": "createContractCall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "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)$" }, "contractId": { "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)$" }, "function": { "type": "string", "minLength": 1, "maxLength": 400 }, "args": { "default": [], "maxItems": 64, "type": "array", "items": {} }, "data": { "type": "string", "maxLength": 20000, "pattern": "^0x([0-9a-fA-F]{2})+$" }, "value": { "default": "0", "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "note": { "type": "string", "maxLength": 500 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "category": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "walletId", "contractId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "$ref": "#/components/schemas/Transfer" } }, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages": { "post": { "summary": "Ask for a message signature (EIP-191, EIP-712, TIP-191, Solana); your team approves it with passkeys. Team signing workspaces only", "description": "Minimum key role: `operate`.", "operationId": "createMessageRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "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)$" }, "type": { "type": "string", "enum": [ "eip191", "eip712", "tip191", "solana" ] }, "message": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 16000 }, { "type": "object", "properties": { "types": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } } }, "primaryType": { "type": "string", "minLength": 1 }, "domain": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "message": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "types", "primaryType", "domain", "message" ] } ] }, "encoding": { "default": "utf8", "type": "string", "enum": [ "utf8", "hex" ] }, "externalId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[\\w.:-]+$" }, "note": { "type": "string", "maxLength": 200 } }, "required": [ "walletId", "type", "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/MessageRequest" } }, "required": [ "message" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Recent message signing requests (100 at most)", "description": "Minimum key role: `read`.", "operationId": "listMessageRequests", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING_APPROVAL", "SIGNED", "REJECTED", "EXPIRED", "FAILED" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageRequest" } } }, "required": [ "messages" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/{id}": { "get": { "summary": "Get a message signing request (and its signature once signed)", "description": "Minimum key role: `read`.", "operationId": "getMessageRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Message request id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/MessageRequest" } }, "required": [ "message" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "summary": "Webhook endpoints (managed in the dashboard)", "description": "Minimum key role: `read`.", "operationId": "listWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "webhooks" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/public-key": { "get": { "summary": "Ed25519 key that signs webhook deliveries", "description": "Minimum key role: `read`.", "operationId": "getWebhookPublicKey", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPublicKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "summary": "Queue a webhook.test delivery", "description": "Minimum key role: `operate`.", "operationId": "testWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Signature, clock or nonce problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "event": { "post": { "summary": "Event delivery (deposit.*, transfer.*, checkout.*, message.*, sweep.*, gas.*, network.*, workspace.*, webhook.test)", "description": "Signed in X-Valtu-Signature (HMAC-SHA256) and X-Valtu-Signature-Ed25519 over \".\". Answer 2xx within 10 s.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Received" } } } } } }