{ "openapi": "3.1.0", "info": { "title": "Crown API & Webhooks", "version": "1.0.0", "description": "Open API 3 docs for Crown API\n\nWebhook events that Crown will POST to your configured endpoint URL. All webhooks expect a 200 OK response. Payloads use kebab-case for all keys to match the Crown API conventions." }, "servers": [ { "url": "https://app.crown-brlv.com", "description": "Production server" } ], "paths": { "/api/v1/accounts/{account-id}/auto-claims/{schedule-id}": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auto-claim schedule retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedule": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ], "description": "The auto-claim schedule" } }, "additionalProperties": false, "required": [ "auto-claim-schedule" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get an auto-claim schedule", "description": "Returns a single auto-claim schedule by ID. Requires the auto-claim-rewards capability." }, "delete": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Auto-claim schedule canceled" }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Cancel an auto-claim schedule", "description": "Cancels a recurring auto-claim schedule and unschedules its job. Requires the auto-claim-rewards capability." } }, "/api/v1/accounts/{account-id}/quotes": { "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset to convert from (e.g., 'fiat/brl', 'eth-base/brlv', 'eth-base/usdc')", "example": "fiat/brl" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset to convert to (e.g., 'fiat/brl', 'eth-base/brlv', 'eth-base/usdc')", "example": "eth-base/usdc" }, "source-amount": { "oneOf": [ { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount of source asset to convert (provide either source-amount OR target-amount, not both)", "example": "100.50" }, { "type": "null" } ] }, "target-amount": { "oneOf": [ { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Desired amount of target asset to receive (provide either source-amount OR target-amount, not both)", "example": "500.25" }, { "type": "null" } ] }, "trade-reason": { "oneOf": [ { "type": "string", "enum": [ "transfer-between-same-entity-accounts" ], "description": "SISBACEN classification for the FX trade. Required when converting between BRL and a non-BRL-pegged asset (e.g., BRL <-> USDC). Ignored for same-currency conversions such as BRL <-> BRLV.", "example": "transfer-between-same-entity-accounts" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "source-asset", "target-asset" ] } } } }, "responses": { "200": { "description": "Quote created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "expires-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the quote expires (millisecond precision)" }, "trade-reason-code": { "type": "string", "description": "Regulatory code for the trade reason", "example": "67995" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/usdc" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the quote", "example": "550e8400-e29b-41d4-a716-446655440000" }, "trade-reason": { "type": "string", "enum": [ "transfer-between-same-entity-accounts" ], "description": "SISBACEN classification for the FX trade", "example": "transfer-between-same-entity-accounts" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted. BRL → 2 dp; USDC/USDT → 6 dp. Always FLOOR-truncated.", "example": "1000.00" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the quote was created (millisecond precision)" }, "pricing": { "type": "object", "properties": { "base-rate": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Units of quote asset per 1 unit of base asset (10-decimal precision, floored)", "example": "5.1307200000" }, "base": { "type": "string", "description": "Base asset symbol", "example": "USDC" }, "quote": { "type": "string", "description": "Quote asset symbol", "example": "BRL" } }, "additionalProperties": false, "required": [ "amount", "base", "quote" ], "description": "Commercial exchange rate, before Crown's spread" }, "spread": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Crown's spread, charged in BRL (2-decimal, rounded UP to the next centavo)", "example": "7.95" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the spread is charged", "example": "fiat/brl" }, "bps": { "type": "integer", "format": "int32", "description": "Spread rate in basis points; present only when the percentage branch of the brokerage formula wins", "example": 80 } }, "additionalProperties": false, "required": [ "amount", "asset" ], "description": "Crown's spread on the conversion" }, "fee": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Service fee charged on the conversion (BRL, 2-decimal, rounded UP)", "example": "2.00" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is charged", "example": "fiat/brl" }, "kind": { "type": "string", "enum": [ "fixed" ], "description": "Fee structure kind", "example": "fixed" } }, "additionalProperties": false, "required": [ "amount", "asset", "kind" ], "description": "Service fee charged on the conversion" }, "iof": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "IOF (Imposto sobre Operações Financeiras) amount (BRL, 2-decimal, rounded UP)", "example": "0.00" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which IOF is charged", "example": "fiat/brl" }, "applicable": { "type": "boolean", "description": "Whether IOF applies to this conversion", "example": false }, "basis-ref": { "type": "string", "description": "Reference to the regulatory basis for IOF treatment", "example": "psav-res-521-2025" } }, "additionalProperties": false, "required": [ "amount", "asset", "applicable", "basis-ref" ], "description": "IOF tax treatment for this conversion" } }, "additionalProperties": false, "required": [ "base-rate", "spread", "fee", "iof" ], "description": "Pricing breakdown: base rate, spread, service fee, IOF" }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received. BRL → 2 dp; USDC/USDT → 6 dp. Always FLOOR-truncated.", "example": "194.914826" }, "vet": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Units of quote asset per 1 unit of base asset (10-decimal precision, floored)", "example": "5.1307200000" }, "base": { "type": "string", "description": "Base asset symbol", "example": "USDC" }, "quote": { "type": "string", "description": "Quote asset symbol", "example": "BRL" } }, "additionalProperties": false, "required": [ "amount", "base", "quote" ], "description": "Valor Efetivo Total — the all-in rate including spread, fee, and IOF" } }, "additionalProperties": false, "required": [ "expires-at", "target-asset", "id", "source-asset", "source-amount", "created-at", "pricing", "target-amount", "vet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a quote for currency/token conversion", "description": "Creates a quote for converting between different assets (fiat currencies and tokens). Either source-amount OR target-amount must be provided, but not both." } }, "/api/v0/orders": { "get": { "responses": { "200": { "description": "Orders list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ], "description": "List of orders" } } }, "additionalProperties": false, "required": [ "orders" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List all orders", "description": "Retrieves a list of all orders for the authenticated user" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quote-id": { "type": "string", "format": "uuid", "description": "Unique identifier of the quote to accept", "example": "550e8400-e29b-41d4-a716-446655440000" }, "source-wallet-address": { "oneOf": [ { "type": "string", "description": "Ethereum wallet address for source tokens (required only when source asset is a token like eth-mainnet/brlv, eth-base/brlv or eth-base/wbrly)", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, { "type": "null" } ] }, "target-wallet-address": { "oneOf": [ { "type": "string", "description": "Ethereum wallet address for receiving tokens. Resolved server-side to an internal wallet, a whitelisted external wallet, or a target wallet. For FX (BRL<->USDC) orders, target wallets must also be FX-whitelisted for the account.", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, { "type": "null" } ] }, "target-end-user-pix-key": { "oneOf": [ { "type": "string", "description": "PIX key of a third-party end-user bank account to receive BRL. Allowed for USDC->BRL and BRLV->BRL orders. The recipient bank account's tax-id must match the tax-id registered on the account the order is executed on. When set, BRL is delivered directly to this PIX key; the API user's own bank account is not touched.", "example": "user@example.com" }, { "type": "null" } ] }, "source-payment-method": { "oneOf": [ { "type": "string", "enum": [ "brcode", "account-balance" ], "description": "How the source BRL is collected. 'brcode' issues a one-time PIX QR for the exact amount that the account pays to fund a BRL->BRLV order; 'account-balance' funds from the account's existing BRL balance and is the default when this field is omitted.", "example": "brcode" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "quote-id" ] } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ] } }, "additionalProperties": false, "required": [ "order" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create an order from a quote", "description": "Creates an order by accepting a quote. Wallet addresses are required only for token assets (eth-base/brlv, eth-mainnet/brlv, eth-base/wbrly). For fiat assets (fiat/brl, fiat/usd), no wallet addresses are needed. Use source-wallet-address for the source wallet and target-wallet-address for the destination wallet." } }, "/api/v1/accounts/{account-id}/orders/{id}": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ] } }, "additionalProperties": false, "required": [ "order" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get an order by ID", "description": "Retrieves a specific order by its ID for the authenticated account" } }, "/api/v0/wallets/{wallet-address}/claims": { "get": { "parameters": [ { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claimable balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "available-balance": { "type": "string", "format": "decimal", "description": "Total available balance that can be claimed", "example": "350.50" } }, "additionalProperties": false, "required": [ "available-balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get claimable balance for a wallet", "description": "Returns the available balance that can be claimed from reward certificates held by the given wallet address." }, "post": { "parameters": [ { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount to claim from reward certificates", "example": "100.00" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Claims request unique identifier", "example": "550e8400-e29b-41d4-a716-446655440003" }, "gross-amount": { "type": "string", "format": "decimal", "description": "Total gross amount of the claims", "example": "100.00" }, "net-amount": { "type": "string", "format": "decimal", "description": "Net amount after taxes and fees", "example": "85.00" }, "tax-amount": { "type": "string", "format": "decimal", "description": "Total tax amount deducted", "example": "15.00" }, "fees": { "type": "string", "format": "decimal", "description": "Processing fees", "example": "0.00" }, "status": { "type": "string", "enum": [ "created", "failed", "completed", "processing", "canceled" ], "description": "Current status of the claims request", "example": "created" }, "updated-at": { "type": "string", "description": "Last update timestamp", "example": "2025-09-30T19:21:57.838913Z" } }, "additionalProperties": false, "required": [ "id", "gross-amount", "net-amount", "tax-amount", "fees", "status", "updated-at" ], "description": "Details of the submitted claim request" } }, "additionalProperties": false, "required": [ "claim" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Submit a claim request for a wallet", "description": "Submits a claim for a specified amount from reward certificates held by the given wallet address. FIFO allocation is restricted to certificates at this wallet." } }, "/api/v1/accounts/{account-id}/orders": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Orders list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ], "description": "List of orders" } } }, "additionalProperties": false, "required": [ "orders" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List all orders", "description": "Retrieves a list of all orders for the authenticated user" }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quote-id": { "type": "string", "format": "uuid", "description": "Unique identifier of the quote to accept", "example": "550e8400-e29b-41d4-a716-446655440000" }, "source-wallet-address": { "oneOf": [ { "type": "string", "description": "Ethereum wallet address for source tokens (required only when source asset is a token like eth-mainnet/brlv, eth-base/brlv or eth-base/wbrly)", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, { "type": "null" } ] }, "target-wallet-address": { "oneOf": [ { "type": "string", "description": "Ethereum wallet address for receiving tokens. Resolved server-side to an internal wallet, a whitelisted external wallet, or a target wallet. For FX (BRL<->USDC) orders, target wallets must also be FX-whitelisted for the account.", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, { "type": "null" } ] }, "target-end-user-pix-key": { "oneOf": [ { "type": "string", "description": "PIX key of a third-party end-user bank account to receive BRL. Allowed for USDC->BRL and BRLV->BRL orders. The recipient bank account's tax-id must match the tax-id registered on the account the order is executed on. When set, BRL is delivered directly to this PIX key; the API user's own bank account is not touched.", "example": "user@example.com" }, { "type": "null" } ] }, "source-payment-method": { "oneOf": [ { "type": "string", "enum": [ "brcode", "account-balance" ], "description": "How the source BRL is collected. 'brcode' issues a one-time PIX QR for the exact amount that the account pays to fund a BRL->BRLV order; 'account-balance' funds from the account's existing BRL balance and is the default when this field is omitted.", "example": "brcode" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "quote-id" ] } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ] } }, "additionalProperties": false, "required": [ "order" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create an order from a quote", "description": "Creates an order by accepting a quote. Wallet addresses are required only for token assets (eth-base/brlv, eth-mainnet/brlv, eth-base/wbrly). For fiat assets (fiat/brl, fiat/usd), no wallet addresses are needed. Use source-wallet-address for the source wallet and target-wallet-address for the destination wallet." } }, "/api/v0/wallets": { "get": { "parameters": [ { "in": "query", "name": "assets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "example": [ "eth-base/brlv", "eth-base/wbrly", "eth-base/eth-mainnet" ] }, "description": "Filter wallets by asset types" }, { "in": "query", "name": "addresses", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "0x1234567890abcdef1234567890abcdef12345678" ] }, "description": "Filter wallets by specific addresses" } ], "responses": { "200": { "description": "Wallets list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the wallet", "example": "My Trading Wallet" }, "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "assets": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "List of assets supported by this wallet", "example": [ "eth-base/brlv", "eth-base/wbrly" ] }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata associated with this wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet is visible in the UI", "example": true } }, "additionalProperties": false, "required": [ "name", "address", "assets", "ui-enabled" ] }, "description": "List of wallets" } }, "additionalProperties": false, "required": [ "wallets" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List wallets", "description": "Returns a list of wallets. Can be filtered by assets and/or addresses." }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet-name": { "type": "string", "description": "Name for the new wallet", "example": "My Trading Wallet" }, "chain": { "type": "string", "enum": [ "tempo", "eth-mainnet", "eth-base" ], "description": "Blockchain that this wallet will be supported on", "example": "eth-base" }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata to associate with the wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet should be visible in the UI (defaults to false)", "example": false } }, "additionalProperties": false, "required": [ "wallet-name", "chain" ] } } } }, "responses": { "200": { "description": "Wallet created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "assets": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "List of supported assets for this wallet", "example": [ "eth-base/brlv", "eth-base/wbrly" ] } }, "additionalProperties": false, "required": [ "address", "assets" ] } }, "additionalProperties": false, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a new wallet", "description": "Creates a new wallet with the specified name and default assets (BRLV and wBRLY if applicable)." } }, "/api/v0/assets/{asset}/withdrawals/{id}": { "get": { "parameters": [ { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset withdrawal retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created withdrawal", "example": "660e8400-e29b-41d4-a716-446655440001" }, "amount": { "type": "string", "format": "decimal", "description": "Amount in BRL being withdrawn", "example": "100.50" }, "method": { "type": "string", "enum": [ "ted", "pix" ], "description": "Withdrawal method (pix or ted)", "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the withdrawal", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal state was last updated" } }, "additionalProperties": false, "required": [ "id", "amount", "method", "state", "created-at", "state-updated-at" ] } }, "additionalProperties": false, "required": [ "withdrawal" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "DEPRECATED: Get a BRL withdrawal by ID", "description": "DEPRECATED: Use /withdrawals/:id instead. Retrieves a specific BRL withdrawal by its ID for the authenticated account." } }, "/api/v0/claims": { "get": { "responses": { "200": { "description": "Claimable balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "available-balance": { "type": "string", "format": "decimal", "description": "Total available balance that can be claimed", "example": "350.50" } }, "additionalProperties": false, "required": [ "available-balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get claimable balance", "description": "Returns the total available balance that can be claimed" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount to claim from reward certificates", "example": "100.00" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Claims request unique identifier", "example": "550e8400-e29b-41d4-a716-446655440003" }, "gross-amount": { "type": "string", "format": "decimal", "description": "Total gross amount of the claims", "example": "100.00" }, "net-amount": { "type": "string", "format": "decimal", "description": "Net amount after taxes and fees", "example": "85.00" }, "tax-amount": { "type": "string", "format": "decimal", "description": "Total tax amount deducted", "example": "15.00" }, "fees": { "type": "string", "format": "decimal", "description": "Processing fees", "example": "0.00" }, "status": { "type": "string", "enum": [ "created", "failed", "completed", "processing", "canceled" ], "description": "Current status of the claims request", "example": "created" }, "updated-at": { "type": "string", "description": "Last update timestamp", "example": "2025-09-30T19:21:57.838913Z" } }, "additionalProperties": false, "required": [ "id", "gross-amount", "net-amount", "tax-amount", "fees", "status", "updated-at" ], "description": "Details of the submitted claim request" } }, "additionalProperties": false, "required": [ "claim" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Submit a claim request", "description": "Submits a claim for a specified amount from reward certificates" } }, "/api/v1/accounts/{account-id}/wallets/{wallet-address}/claims/certificates": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claimable certificates retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate unique identifier", "example": "550e8400-e29b-41d4-a716-446655440010" }, "status": { "type": "string", "enum": [ "accruing", "frozen" ], "description": "Current status of the certificate", "example": "accruing" }, "claimable-amount": { "type": "string", "format": "decimal", "description": "Amount currently claimable from this certificate", "example": "150.25" } }, "additionalProperties": false, "required": [ "certificate-id", "status", "claimable-amount" ] }, "description": "List of reward certificates with claimable amounts" }, "total-claimable": { "type": "string", "format": "decimal", "description": "Total claimable amount across all certificates", "example": "350.50" } }, "additionalProperties": false, "required": [ "certificates", "total-claimable" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List claimable reward certificates for a wallet", "description": "Returns the reward certificates with their claimable amounts for the given wallet address." } }, "/api/v1/accounts/{account-id}/assets/{asset}/deposits": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "responses": { "200": { "description": "Deposits list retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRL deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "pix" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in BRL", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "credited" }, "coordinates": { "type": "object", "properties": { "source-tax-id": { "type": "string", "description": "Tax ID of the sender (CPF/CNPJ)", "example": "12345678900" }, "source-bank-code": { "type": "string", "description": "Bank code of the sender", "example": "341" }, "source-type": { "type": "string", "enum": [ "ted", "pix" ], "description": "Type of BRL transfer", "example": "pix" }, "source-account-number": { "type": "string", "description": "Account number of the sender", "example": "12345-6" }, "source-branch-code": { "type": "string", "description": "Branch code of the sender", "example": "0001" }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "source-tax-id", "source-bank-code", "source-type", "source-account-number", "source-branch-code" ], "description": "Source banking information for the BRL deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at", "processed-at" ], "description": "List of BRL deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "BRL Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRLV deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "brlv" ], "description": "Type of deposit", "example": "brlv" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv" ], "description": "The BRLV asset of the deposit", "example": "eth-base/brlv" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the BRLV deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the BRLV deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "asset", "status", "coordinates", "tx-hash", "created-at" ], "description": "List of BRLV deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "BRLV Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the token deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the token deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "token" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the token deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "asset": { "type": "string", "enum": [ "eth-base/usdt", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/usdc" ], "description": "The token asset of the deposit", "example": "eth-base/usdc" } }, "additionalProperties": false, "required": [ "amount", "coordinates", "tx-hash", "type", "processed-at", "status", "id", "created-at", "asset" ], "description": "List of token deposits (USDC/USDT)" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "Token Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the USD deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "manual-fx" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in USD", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Source and target information for the deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "oneOf": [ { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at" ], "description": "List of USD deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "USD Deposits" } ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List deposits by asset", "description": "Retrieves a list of deposits for the authenticated user for a specific asset type. Asset can be 'brl', 'usd', 'usdc' or 'usdt'" } }, "/api/v1/accounts/{account-id}/tax-exemption/progress": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tax exemption progress retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax-exemption-progress": { "type": "object", "properties": { "claims-amount": { "type": "string", "format": "decimal" }, "other-disposals-amount": { "type": "string", "format": "decimal" }, "total-used": { "type": "string", "format": "decimal" }, "limit": { "type": "string", "format": "decimal" }, "remaining": { "type": "string", "format": "decimal" } }, "additionalProperties": false, "required": [ "claims-amount", "other-disposals-amount", "total-used", "limit", "remaining" ] } }, "additionalProperties": false, "required": [ "tax-exemption-progress" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get monthly tax exemption progress", "description": "Returns the current month's tax exemption progress for Brazilian accounts. Shows the breakdown of disposals that count toward the R$35,000 monthly limit: resgates (claims) and outras alienações (burns and BRLV target-wallet transfers)." } }, "/api/v0/tax-exemption/progress": { "get": { "responses": { "200": { "description": "Tax exemption progress retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax-exemption-progress": { "type": "object", "properties": { "claims-amount": { "type": "string", "format": "decimal" }, "other-disposals-amount": { "type": "string", "format": "decimal" }, "total-used": { "type": "string", "format": "decimal" }, "limit": { "type": "string", "format": "decimal" }, "remaining": { "type": "string", "format": "decimal" } }, "additionalProperties": false, "required": [ "claims-amount", "other-disposals-amount", "total-used", "limit", "remaining" ] } }, "additionalProperties": false, "required": [ "tax-exemption-progress" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get monthly tax exemption progress", "description": "Returns the current month's tax exemption progress for Brazilian accounts. Shows the breakdown of disposals that count toward the R$35,000 monthly limit: resgates (claims) and outras alienações (burns and BRLV target-wallet transfers)." } }, "/api/v1/accounts/{account-id}/transfers": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "source-address", "required": false, "schema": { "type": "string", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "description": "Filter by source wallet address" }, { "in": "query", "name": "target-address", "required": false, "schema": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "description": "Filter by target wallet address" }, { "in": "query", "name": "asset", "required": false, "schema": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "example": "eth-base/brlv" }, "description": "Filter by asset" }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "example": "completed" }, "description": "Filter by transfer state" } ], "responses": { "200": { "description": "Transfers list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount being transferred", "example": "100.50" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" }, "tx-hash": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Blockchain transaction hash once available", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transfer", "example": "660e8400-e29b-41d4-a716-446655440003" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset being transferred", "example": "eth-base/brlv" } }, "additionalProperties": false, "required": [ "amount", "state-updated-at", "tx-hash", "state", "source-address", "id", "target-address", "created-at", "asset" ] }, "description": "List of transfers" } }, "additionalProperties": false, "required": [ "transfers" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List transfers", "description": "Retrieves a list of token transfers for the authenticated user. Can be filtered by source-address, target-address, asset, or state." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-address": { "type": "string", "description": "Source wallet address (0x...)", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset to transfer (only token assets supported: eth-base/brlv, eth-base/wbrly)", "example": "eth-base/brlv" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount of tokens to transfer", "example": "100.50" }, "target-address": { "type": "string", "description": "Target wallet address (0x...)", "example": "0x1234567890abcdef1234567890abcdef12345678" } }, "additionalProperties": false, "required": [ "source-address", "asset", "amount", "target-address" ] } } } }, "responses": { "200": { "description": "Transfer created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount being transferred", "example": "100.50" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" }, "tx-hash": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Blockchain transaction hash once available", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transfer", "example": "660e8400-e29b-41d4-a716-446655440003" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset being transferred", "example": "eth-base/brlv" } }, "additionalProperties": false, "required": [ "amount", "state-updated-at", "tx-hash", "state", "source-address", "id", "target-address", "created-at", "asset" ], "description": "Details of the created transfer" } }, "additionalProperties": false, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Transfer tokens between wallets", "description": "Transfer tokens from a source wallet to a target wallet. Both source and target should be EVM wallet addresses (0x...)." } }, "/api/v1/accounts/{account-id}/wallets/{wallet-id}/metadata": { "patch": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata to associate with the wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet should be visible in the UI", "example": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Wallet metadata updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Wallet ID", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "name": { "type": "string", "description": "Name of the wallet", "example": "My Trading Wallet" }, "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet is visible in the UI", "example": true }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata associated with this wallet", "example": { "label": "treasury" } } }, "additionalProperties": false, "required": [ "id", "name", "address", "ui-enabled" ] } }, "additionalProperties": false, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Update wallet metadata", "description": "Updates the metadata and/or UI visibility for a specific wallet owned by the authenticated user." } }, "/api/v0/withdrawals/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Withdrawal retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get a withdrawal by ID", "description": "Retrieves details of a specific withdrawal" } }, "/api/v1/accounts/{account-id}/wallets/{wallet-address}/claims": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claimable balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "available-balance": { "type": "string", "format": "decimal", "description": "Total available balance that can be claimed", "example": "350.50" } }, "additionalProperties": false, "required": [ "available-balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get claimable balance for a wallet", "description": "Returns the available balance that can be claimed from reward certificates held by the given wallet address." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount to claim from reward certificates", "example": "100.00" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Claims request unique identifier", "example": "550e8400-e29b-41d4-a716-446655440003" }, "gross-amount": { "type": "string", "format": "decimal", "description": "Total gross amount of the claims", "example": "100.00" }, "net-amount": { "type": "string", "format": "decimal", "description": "Net amount after taxes and fees", "example": "85.00" }, "tax-amount": { "type": "string", "format": "decimal", "description": "Total tax amount deducted", "example": "15.00" }, "fees": { "type": "string", "format": "decimal", "description": "Processing fees", "example": "0.00" }, "status": { "type": "string", "enum": [ "created", "failed", "completed", "processing", "canceled" ], "description": "Current status of the claims request", "example": "created" }, "updated-at": { "type": "string", "description": "Last update timestamp", "example": "2025-09-30T19:21:57.838913Z" } }, "additionalProperties": false, "required": [ "id", "gross-amount", "net-amount", "tax-amount", "fees", "status", "updated-at" ], "description": "Details of the submitted claim request" } }, "additionalProperties": false, "required": [ "claim" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Submit a claim request for a wallet", "description": "Submits a claim for a specified amount from reward certificates held by the given wallet address. FIFO allocation is restricted to certificates at this wallet." } }, "/api/v1/accounts/{account-id}/withdrawals": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "asset", "required": false, "schema": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "Filter by asset" } ], "responses": { "200": { "description": "Withdrawals retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ], "description": "List of withdrawals (BRL PIX, BRL TED, or tokens)" } } }, "additionalProperties": false, "required": [ "withdrawals" ], "title": "Withdrawals" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List withdrawals", "description": "Lists all withdrawals for the authenticated account" }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "method": { "enum": [ "pix" ], "example": "pix" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "pix-key": { "type": "string", "description": "PIX key", "example": "user@example.com" } }, "additionalProperties": false, "required": [ "asset", "method", "amount", "pix-key" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "method": { "enum": [ "ted" ], "example": "ted" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "bank-code": { "type": "string" }, "branch-number": { "type": "string" }, "account-number": { "type": "string" }, "account-holder-name": { "type": "string" }, "account-holder-tax-id": { "oneOf": [ { "type": "string" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "asset", "method", "amount", "bank-code", "branch-number", "account-number", "account-holder-name", "account-holder-tax-id" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "destination-wallet-address": { "type": "string", "description": "External wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" } }, "additionalProperties": false, "required": [ "asset", "amount", "destination-wallet-address" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } } } }, "responses": { "200": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } }, "additionalProperties": false, "required": [ "withdrawal" ], "title": "Create Withdrawal Response" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a withdrawal", "description": "Creates a withdrawal for fiat (PIX/TED) or tokens. For fiat BRL, use asset 'fiat/brl' with method 'pix' or 'ted'. For tokens, use asset like 'eth-base/usdc' with method 'token'." } }, "/api/v1/accounts/{account-id}/claims/certificates": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Claimable certificates retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate unique identifier", "example": "550e8400-e29b-41d4-a716-446655440010" }, "status": { "type": "string", "enum": [ "accruing", "frozen" ], "description": "Current status of the certificate", "example": "accruing" }, "claimable-amount": { "type": "string", "format": "decimal", "description": "Amount currently claimable from this certificate", "example": "150.25" } }, "additionalProperties": false, "required": [ "certificate-id", "status", "claimable-amount" ] }, "description": "List of reward certificates with claimable amounts" }, "total-claimable": { "type": "string", "format": "decimal", "description": "Total claimable amount across all certificates", "example": "350.50" } }, "additionalProperties": false, "required": [ "certificates", "total-claimable" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List claimable reward certificates", "description": "Returns a list of reward certificates with their claimable amounts" } }, "/api/v1/accounts/{account-id}/auto-claims/{schedule-id}/skips/{skip-id}": { "delete": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "skip-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Skip window removed" }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Remove an auto-claim skip window", "description": "Deletes a skip window so the schedule runs again on those dates. Requires the auto-claim-rewards capability." } }, "/api/v1/accounts/{account-id}/assets/{asset}/balance": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "responses": { "200": { "description": "Asset balance retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "object", "properties": { "running-balance": { "type": "string", "format": "decimal", "description": "Balance rendered at the asset's decimal scale (brl=2, usdc=6, brlv=18).", "example": "0.000000000000000000" } }, "additionalProperties": false, "required": [ "running-balance" ] } }, "additionalProperties": false, "required": [ "balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get balance by asset", "description": "Retrieves the account's balance for a given asset." } }, "/api/v0/transfers": { "get": { "parameters": [ { "in": "query", "name": "source-address", "required": false, "schema": { "type": "string", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "description": "Filter by source wallet address" }, { "in": "query", "name": "target-address", "required": false, "schema": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "description": "Filter by target wallet address" }, { "in": "query", "name": "asset", "required": false, "schema": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "example": "eth-base/brlv" }, "description": "Filter by asset" }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "example": "completed" }, "description": "Filter by transfer state" } ], "responses": { "200": { "description": "Transfers list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount being transferred", "example": "100.50" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" }, "tx-hash": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Blockchain transaction hash once available", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transfer", "example": "660e8400-e29b-41d4-a716-446655440003" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset being transferred", "example": "eth-base/brlv" } }, "additionalProperties": false, "required": [ "amount", "state-updated-at", "tx-hash", "state", "source-address", "id", "target-address", "created-at", "asset" ] }, "description": "List of transfers" } }, "additionalProperties": false, "required": [ "transfers" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List transfers", "description": "Retrieves a list of token transfers for the authenticated user. Can be filtered by source-address, target-address, asset, or state." }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-address": { "type": "string", "description": "Source wallet address (0x...)", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset to transfer (only token assets supported: eth-base/brlv, eth-base/wbrly)", "example": "eth-base/brlv" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount of tokens to transfer", "example": "100.50" }, "target-address": { "type": "string", "description": "Target wallet address (0x...)", "example": "0x1234567890abcdef1234567890abcdef12345678" } }, "additionalProperties": false, "required": [ "source-address", "asset", "amount", "target-address" ] } } } }, "responses": { "200": { "description": "Transfer created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount being transferred", "example": "100.50" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" }, "tx-hash": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Blockchain transaction hash once available", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transfer", "example": "660e8400-e29b-41d4-a716-446655440003" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset being transferred", "example": "eth-base/brlv" } }, "additionalProperties": false, "required": [ "amount", "state-updated-at", "tx-hash", "state", "source-address", "id", "target-address", "created-at", "asset" ], "description": "Details of the created transfer" } }, "additionalProperties": false, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Transfer tokens between wallets", "description": "Transfer tokens from a source wallet to a target wallet. Both source and target should be EVM wallet addresses (0x...)." } }, "/api/v0/withdrawals": { "get": { "parameters": [ { "in": "query", "name": "asset", "required": false, "schema": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "Filter by asset" } ], "responses": { "200": { "description": "Withdrawals retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ], "description": "List of withdrawals (BRL PIX, BRL TED, or tokens)" } } }, "additionalProperties": false, "required": [ "withdrawals" ], "title": "Withdrawals" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List withdrawals", "description": "Lists all withdrawals for the authenticated account" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "method": { "enum": [ "pix" ], "example": "pix" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "pix-key": { "type": "string", "description": "PIX key", "example": "user@example.com" } }, "additionalProperties": false, "required": [ "asset", "method", "amount", "pix-key" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "method": { "enum": [ "ted" ], "example": "ted" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "bank-code": { "type": "string" }, "branch-number": { "type": "string" }, "account-number": { "type": "string" }, "account-holder-name": { "type": "string" }, "account-holder-tax-id": { "oneOf": [ { "type": "string" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "asset", "method", "amount", "bank-code", "branch-number", "account-number", "account-holder-name", "account-holder-tax-id" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ] }, "destination-wallet-address": { "type": "string", "description": "External wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" } }, "additionalProperties": false, "required": [ "asset", "amount", "destination-wallet-address" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } } } }, "responses": { "200": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } }, "additionalProperties": false, "required": [ "withdrawal" ], "title": "Create Withdrawal Response" } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a withdrawal", "description": "Creates a withdrawal for fiat (PIX/TED) or tokens. For fiat BRL, use asset 'fiat/brl' with method 'pix' or 'ted'. For tokens, use asset like 'eth-base/usdc' with method 'token'." } }, "/api/v0/wallets/{wallet-id}/metadata": { "patch": { "parameters": [ { "in": "path", "name": "wallet-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata to associate with the wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet should be visible in the UI", "example": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Wallet metadata updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Wallet ID", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "name": { "type": "string", "description": "Name of the wallet", "example": "My Trading Wallet" }, "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet is visible in the UI", "example": true }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata associated with this wallet", "example": { "label": "treasury" } } }, "additionalProperties": false, "required": [ "id", "name", "address", "ui-enabled" ] } }, "additionalProperties": false, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Update wallet metadata", "description": "Updates the metadata and/or UI visibility for a specific wallet owned by the authenticated user." } }, "/api/v1/accounts": { "get": { "responses": { "200": { "description": "Account and sub-accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the account", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "alias": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable alias for the account", "example": "Trading account" }, "status": { "type": "string", "description": "Current status of the account. A provisioned account is 'pending-setup' or 'active'. A sub-account still in creation is projected as a pending account carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008).", "example": "active" }, "external-id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier associated with the account", "example": "ext-12345" }, "parent-id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Parent account id when this is a sub-account; null for top-level" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "alias", "status", "external-id", "created-at" ] } } }, "additionalProperties": false, "required": [ "accounts" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List accounts", "description": "Lists the authenticated account together with its sub-accounts. The caller's own record always comes first, with a null parent-id. Sub-accounts (every account whose parent is the caller, each carrying the caller's id as its parent-id) are included only for callers with the manage-holders capability; without it, the response contains the caller alone. Requires API access." }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tax-id": { "type": "string", "description": "Sub-account holder's tax id", "example": "12345678901" }, "tax-document-type": { "type": "string", "enum": [ "passport", "national-id", "cpf" ], "description": "Identity document backing the tax id (individuals only)" }, "tax-residence": { "type": "string", "description": "Tax residence country, ISO-3", "example": "BRA" }, "kyc-attestation-id": { "type": "string", "description": "Partner's reference to its own completed KYC of the holder" }, "reward-tier": { "type": "number", "format": "double", "enum": [ 93.5, 90, 97 ], "description": "CDI reward tier (%) for the sub-account. The parent account must hold the matching subaccounts--tier capability.", "example": 97 }, "external-wallets": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "On-chain destination address", "example": "0xabc..." }, "custody-country": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custodian country, ISO-3", "example": "BRA" }, "custody-type": { "oneOf": [ { "type": "string", "enum": [ "self", "exchange" ] }, { "type": "null" } ], "description": "Self-custody or exchange custody" }, "custodian-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custodian/exchange name" } }, "additionalProperties": false, "required": [ "address" ] } } }, "additionalProperties": false, "required": [ "tax-id", "tax-document-type", "tax-residence", "kyc-attestation-id", "reward-tier" ] } } } }, "responses": { "201": { "description": "Sub-account creation requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the account", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "alias": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable alias for the account", "example": "Trading account" }, "status": { "type": "string", "description": "Current status of the account. A provisioned account is 'pending-setup' or 'active'. A sub-account still in creation is projected as a pending account carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008).", "example": "active" }, "external-id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier associated with the account", "example": "ext-12345" }, "parent-id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Parent account id when this is a sub-account; null for top-level" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "alias", "status", "external-id", "created-at" ] } }, "additionalProperties": false, "required": [ "account" ] } } } }, "200": { "description": "An equivalent non-terminal request already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the account", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "alias": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable alias for the account", "example": "Trading account" }, "status": { "type": "string", "description": "Current status of the account. A provisioned account is 'pending-setup' or 'active'. A sub-account still in creation is projected as a pending account carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008).", "example": "active" }, "external-id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier associated with the account", "example": "ext-12345" }, "parent-id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Parent account id when this is a sub-account; null for top-level" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "alias", "status", "external-id", "created-at" ] } }, "additionalProperties": false, "required": [ "account" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a sub-account", "description": "Requests creation of a known-taxpayer individual sub-account under the authenticated partner account. Request-first: the request enters compliance review and the sub-account is provisioned on approval. Requires the manage-holders capability." } }, "/api/v0/orders/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "base-rate": { "type": "string", "format": "decimal", "description": "Base exchange rate between assets", "example": "1.0000" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order state was last updated" }, "qr-code-base64": { "type": "string", "description": "Base64-encoded PNG QR code rendered from the brcode payload." }, "fee-amount": { "type": "string", "format": "decimal", "description": "Fee charged for the order.", "example": "0.50" }, "expiration": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the brcode expires." }, "effective-rate": { "type": "string", "format": "decimal", "description": "Effective rate including fees", "example": "0.9950" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the order", "example": "created" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/brlv" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created order", "example": "660e8400-e29b-41d4-a716-446655440001" }, "quote-id": { "type": "string", "format": "uuid", "description": "Identifier of the quote this order was created from", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fee-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is denominated.", "example": "fiat/brl" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted", "example": "100.50" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the order was created" }, "brcode": { "type": "string", "description": "EMV PIX copy-paste payload for the brcode (present only for source-payment-method brcode).", "example": "00020101021226890014br.gov.bcb.pix..." }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received", "example": "99.75" } }, "additionalProperties": false, "required": [ "base-rate", "state-updated-at", "effective-rate", "state", "target-asset", "id", "quote-id", "source-asset", "source-amount", "created-at", "target-amount" ] } }, "additionalProperties": false, "required": [ "order" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get an order by ID", "description": "Retrieves a specific order by its ID for the authenticated account" } }, "/api/v1/accounts/{account-id}/auto-claims/{schedule-id}/skips": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Skip windows retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-skips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Skip window unique identifier" }, "starts-on": { "type": "string", "description": "First day skipped, inclusive", "example": "2026-07-01" }, "ends-on": { "type": "string", "description": "Last day skipped, inclusive", "example": "2026-07-15" }, "reason": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Note recorded with the skip, or null" }, "created-at": { "type": "string", "description": "Creation timestamp" } }, "additionalProperties": false, "required": [ "id", "starts-on", "ends-on", "reason", "created-at" ] }, "description": "Active skip windows for the schedule" } }, "additionalProperties": false, "required": [ "auto-claim-skips" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List auto-claim skip windows", "description": "Returns the active skip windows for the schedule. Requires the auto-claim-rewards capability." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Single day to skip (YYYY-MM-DD); shorthand for from=to", "example": "2026-07-01" }, "from": { "type": "string", "description": "Start of the skip window, inclusive (YYYY-MM-DD)", "example": "2026-07-01" }, "to": { "type": "string", "description": "End of the skip window, inclusive (YYYY-MM-DD)", "example": "2026-07-15" }, "reason": { "type": "string", "description": "Optional note recorded with the skip" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Skip window created", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-skip": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Skip window unique identifier" }, "starts-on": { "type": "string", "description": "First day skipped, inclusive", "example": "2026-07-01" }, "ends-on": { "type": "string", "description": "Last day skipped, inclusive", "example": "2026-07-15" }, "reason": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Note recorded with the skip, or null" }, "created-at": { "type": "string", "description": "Creation timestamp" } }, "additionalProperties": false, "required": [ "id", "starts-on", "ends-on", "reason", "created-at" ], "description": "The created skip window" } }, "additionalProperties": false, "required": [ "auto-claim-skip" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Skip an auto-claim on a date or period", "description": "Suppresses the schedule's runs on a single date or across an inclusive date range without deleting it; runs resume automatically after the window. Requires the auto-claim-rewards capability." } }, "/api/v1/accounts/{account-id}/wallets/{wallet-address}/auto-claims": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auto-claim schedules retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedules": { "type": "array", "items": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ] }, "description": "Auto-claim schedules for the account" } }, "additionalProperties": false, "required": [ "auto-claim-schedules" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List auto-claim schedules for a wallet", "description": "Returns the recurring auto-claim schedules configured for the given wallet address. Requires the auto-claim-rewards capability." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "max-amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Claim up to this amount each run; if less is available, claims what's available", "example": "100.00" }, "cron": { "type": "string", "description": "UNIX cron expression (5 fields). Must fire at most once per day", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "max-amount", "cron" ] } } } }, "responses": { "200": { "description": "Auto-claim schedule created", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedule": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ], "description": "The auto-claim schedule" } }, "additionalProperties": false, "required": [ "auto-claim-schedule" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a wallet-scoped auto-claim schedule", "description": "Schedules a recurring claim of up to the given amount on a UNIX cron (at least daily) from reward certificates held by the given wallet address. Requires the auto-claim-rewards capability." } }, "/api/v0/quotes": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset to convert from (e.g., 'fiat/brl', 'eth-base/brlv', 'eth-base/usdc')", "example": "fiat/brl" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset to convert to (e.g., 'fiat/brl', 'eth-base/brlv', 'eth-base/usdc')", "example": "eth-base/usdc" }, "source-amount": { "oneOf": [ { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount of source asset to convert (provide either source-amount OR target-amount, not both)", "example": "100.50" }, { "type": "null" } ] }, "target-amount": { "oneOf": [ { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Desired amount of target asset to receive (provide either source-amount OR target-amount, not both)", "example": "500.25" }, { "type": "null" } ] }, "trade-reason": { "oneOf": [ { "type": "string", "enum": [ "transfer-between-same-entity-accounts" ], "description": "SISBACEN classification for the FX trade. Required when converting between BRL and a non-BRL-pegged asset (e.g., BRL <-> USDC). Ignored for same-currency conversions such as BRL <-> BRLV.", "example": "transfer-between-same-entity-accounts" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "source-asset", "target-asset" ] } } } }, "responses": { "200": { "description": "Quote created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "expires-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the quote expires (millisecond precision)" }, "trade-reason-code": { "type": "string", "description": "Regulatory code for the trade reason", "example": "67995" }, "target-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted to", "example": "eth-base/usdc" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the quote", "example": "550e8400-e29b-41d4-a716-446655440000" }, "trade-reason": { "type": "string", "enum": [ "transfer-between-same-entity-accounts" ], "description": "SISBACEN classification for the FX trade", "example": "transfer-between-same-entity-accounts" }, "source-asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "The asset being converted from", "example": "fiat/brl" }, "source-amount": { "type": "string", "format": "decimal", "description": "Amount of source asset to be converted. BRL → 2 dp; USDC/USDT → 6 dp. Always FLOOR-truncated.", "example": "1000.00" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the quote was created (millisecond precision)" }, "pricing": { "type": "object", "properties": { "base-rate": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Units of quote asset per 1 unit of base asset (10-decimal precision, floored)", "example": "5.1307200000" }, "base": { "type": "string", "description": "Base asset symbol", "example": "USDC" }, "quote": { "type": "string", "description": "Quote asset symbol", "example": "BRL" } }, "additionalProperties": false, "required": [ "amount", "base", "quote" ], "description": "Commercial exchange rate, before Crown's spread" }, "spread": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Crown's spread, charged in BRL (2-decimal, rounded UP to the next centavo)", "example": "7.95" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the spread is charged", "example": "fiat/brl" }, "bps": { "type": "integer", "format": "int32", "description": "Spread rate in basis points; present only when the percentage branch of the brokerage formula wins", "example": 80 } }, "additionalProperties": false, "required": [ "amount", "asset" ], "description": "Crown's spread on the conversion" }, "fee": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Service fee charged on the conversion (BRL, 2-decimal, rounded UP)", "example": "2.00" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which the fee is charged", "example": "fiat/brl" }, "kind": { "type": "string", "enum": [ "fixed" ], "description": "Fee structure kind", "example": "fixed" } }, "additionalProperties": false, "required": [ "amount", "asset", "kind" ], "description": "Service fee charged on the conversion" }, "iof": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "IOF (Imposto sobre Operações Financeiras) amount (BRL, 2-decimal, rounded UP)", "example": "0.00" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ], "description": "Asset in which IOF is charged", "example": "fiat/brl" }, "applicable": { "type": "boolean", "description": "Whether IOF applies to this conversion", "example": false }, "basis-ref": { "type": "string", "description": "Reference to the regulatory basis for IOF treatment", "example": "psav-res-521-2025" } }, "additionalProperties": false, "required": [ "amount", "asset", "applicable", "basis-ref" ], "description": "IOF tax treatment for this conversion" } }, "additionalProperties": false, "required": [ "base-rate", "spread", "fee", "iof" ], "description": "Pricing breakdown: base rate, spread, service fee, IOF" }, "target-amount": { "type": "string", "format": "decimal", "description": "Amount of target asset to be received. BRL → 2 dp; USDC/USDT → 6 dp. Always FLOOR-truncated.", "example": "194.914826" }, "vet": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Units of quote asset per 1 unit of base asset (10-decimal precision, floored)", "example": "5.1307200000" }, "base": { "type": "string", "description": "Base asset symbol", "example": "USDC" }, "quote": { "type": "string", "description": "Quote asset symbol", "example": "BRL" } }, "additionalProperties": false, "required": [ "amount", "base", "quote" ], "description": "Valor Efetivo Total — the all-in rate including spread, fee, and IOF" } }, "additionalProperties": false, "required": [ "expires-at", "target-asset", "id", "source-asset", "source-amount", "created-at", "pricing", "target-amount", "vet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a quote for currency/token conversion", "description": "Creates a quote for converting between different assets (fiat currencies and tokens). Either source-amount OR target-amount must be provided, but not both." } }, "/api/v1/accounts/{account-id}/auto-claims/{schedule-id}/resume": { "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auto-claim schedule resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedule": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ], "description": "The auto-claim schedule" } }, "additionalProperties": false, "required": [ "auto-claim-schedule" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Resume a paused auto-claim schedule", "description": "Re-enables a paused schedule so it claims again on its next fires. Requires the auto-claim-rewards capability." } }, "/api/v0/assets/{asset}/withdrawals": { "get": { "parameters": [ { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "responses": { "200": { "description": "Asset withdrawals list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created withdrawal", "example": "660e8400-e29b-41d4-a716-446655440001" }, "amount": { "type": "string", "format": "decimal", "description": "Amount in BRL being withdrawn", "example": "100.50" }, "method": { "type": "string", "enum": [ "ted", "pix" ], "description": "Withdrawal method (pix or ted)", "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the withdrawal", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal state was last updated" } }, "additionalProperties": false, "required": [ "id", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "List of withdrawals" } } }, "additionalProperties": false, "required": [ "withdrawals" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "DEPRECATED: List BRL withdrawals by asset", "description": "DEPRECATED: Use /withdrawals instead. Retrieves a list of all BRL withdrawals for the authenticated user." }, "post": { "parameters": [ { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "ted", "pix" ], "description": "Withdrawal method. Must be either 'pix' or 'ted'", "example": "pix" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount in BRL to withdraw", "example": "100.50" }, "pix-key": { "type": "string", "description": "PIX key (email, phone, CPF/CNPJ, or random key). Required when method is 'pix'", "example": "user@example.com" }, "bank-code": { "type": "string", "description": "3-digit Brazilian bank code. Required when method is 'ted'", "example": "001" }, "branch-number": { "type": "string", "description": "4-5 digit Brazilian branch number. Required when method is 'ted'", "example": "1234" }, "account-number": { "type": "string", "description": "Brazilian account number. Required when method is 'ted'", "example": "12345678" }, "account-holder-name": { "type": "string", "description": "Name of the account holder. Required when method is 'ted'", "example": "John Doe" }, "account-holder-tax-id": { "oneOf": [ { "type": "string" }, { "type": "string" } ], "description": "CPF or CNPJ of the account holder. Required when method is 'ted'", "example": "12345678901" } }, "additionalProperties": false, "required": [ "method", "amount" ] } } } }, "responses": { "200": { "description": "Asset withdrawal created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created withdrawal", "example": "660e8400-e29b-41d4-a716-446655440001" }, "amount": { "type": "string", "format": "decimal", "description": "Amount in BRL being withdrawn", "example": "100.50" }, "method": { "type": "string", "enum": [ "ted", "pix" ], "description": "Withdrawal method (pix or ted)", "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "description": "Current state of the withdrawal", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the withdrawal state was last updated" } }, "additionalProperties": false, "required": [ "id", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "Details of the created withdrawal" } }, "additionalProperties": false, "required": [ "withdrawal" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "DEPRECATED: Create a BRL withdrawal", "description": "DEPRECATED: Use /withdrawals instead. Creates a BRL withdrawal with PIX or TED methods. For PIX withdrawals, only a pix-key is required. For TED withdrawals, full bank account details are required." } }, "/api/v1/accounts/{account-id}": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the account", "example": "019712cf-c86d-703f-85b8-bdaa4fc8d254" }, "alias": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable alias for the account", "example": "Trading account" }, "status": { "type": "string", "description": "Current status of the account. A provisioned account is 'pending-setup' or 'active'. A sub-account still in creation is projected as a pending account carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008).", "example": "active" }, "external-id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "External identifier associated with the account", "example": "ext-12345" }, "parent-id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Parent account id when this is a sub-account; null for top-level" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "alias", "status", "external-id", "created-at" ] } }, "additionalProperties": false, "required": [ "account" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get an account by ID", "description": "Fetches a single account by ID. The account must be either the authenticated account itself or one of its sub-accounts (an account whose parent is the caller); any other id is rejected by the access check. Returns the account's profile, status, type, and capabilities." } }, "/api/v0/assets/{asset}/deposits": { "get": { "parameters": [ { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "responses": { "200": { "description": "Deposits list retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRL deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "pix" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in BRL", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "credited" }, "coordinates": { "type": "object", "properties": { "source-tax-id": { "type": "string", "description": "Tax ID of the sender (CPF/CNPJ)", "example": "12345678900" }, "source-bank-code": { "type": "string", "description": "Bank code of the sender", "example": "341" }, "source-type": { "type": "string", "enum": [ "ted", "pix" ], "description": "Type of BRL transfer", "example": "pix" }, "source-account-number": { "type": "string", "description": "Account number of the sender", "example": "12345-6" }, "source-branch-code": { "type": "string", "description": "Branch code of the sender", "example": "0001" }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "source-tax-id", "source-bank-code", "source-type", "source-account-number", "source-branch-code" ], "description": "Source banking information for the BRL deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at", "processed-at" ], "description": "List of BRL deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "BRL Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRLV deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "brlv" ], "description": "Type of deposit", "example": "brlv" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv" ], "description": "The BRLV asset of the deposit", "example": "eth-base/brlv" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the BRLV deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the BRLV deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "asset", "status", "coordinates", "tx-hash", "created-at" ], "description": "List of BRLV deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "BRLV Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the token deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the token deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "token" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the token deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "asset": { "type": "string", "enum": [ "eth-base/usdt", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/usdc" ], "description": "The token asset of the deposit", "example": "eth-base/usdc" } }, "additionalProperties": false, "required": [ "amount", "coordinates", "tx-hash", "type", "processed-at", "status", "id", "created-at", "asset" ], "description": "List of token deposits (USDC/USDT)" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "Token Deposits" }, { "type": "object", "properties": { "deposits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the USD deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "manual-fx" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in USD", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Source and target information for the deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "oneOf": [ { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at" ], "description": "List of USD deposits" } } }, "additionalProperties": false, "required": [ "deposits" ], "title": "USD Deposits" } ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List deposits by asset", "description": "Retrieves a list of deposits for the authenticated user for a specific asset type. Asset can be 'brl', 'usd', 'usdc' or 'usdt'" } }, "/api/v1/accounts/{account-id}/assets/{asset}/deposits/{id}": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deposit retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "deposit": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRL deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "pix" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in BRL", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "credited" }, "coordinates": { "type": "object", "properties": { "source-tax-id": { "type": "string", "description": "Tax ID of the sender (CPF/CNPJ)", "example": "12345678900" }, "source-bank-code": { "type": "string", "description": "Bank code of the sender", "example": "341" }, "source-type": { "type": "string", "enum": [ "ted", "pix" ], "description": "Type of BRL transfer", "example": "pix" }, "source-account-number": { "type": "string", "description": "Account number of the sender", "example": "12345-6" }, "source-branch-code": { "type": "string", "description": "Branch code of the sender", "example": "0001" }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "source-tax-id", "source-bank-code", "source-type", "source-account-number", "source-branch-code" ], "description": "Source banking information for the BRL deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at", "processed-at" ], "title": "BRL Deposit" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the BRLV deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "brlv" ], "description": "Type of deposit", "example": "brlv" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "asset": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv" ], "description": "The BRLV asset of the deposit", "example": "eth-base/brlv" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the BRLV deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the BRLV deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" } }, "additionalProperties": false, "required": [ "id", "type", "amount", "asset", "status", "coordinates", "tx-hash", "created-at" ], "title": "BRLV Deposit" }, { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit", "example": "100.500000000000000000" }, "coordinates": { "type": "object", "properties": { "source-chain": { "type": "string", "description": "Source blockchain network", "example": "eth-base" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c" } }, "additionalProperties": false, "required": [ "source-chain", "source-address", "target-address" ], "description": "Source and target wallet addresses for the token deposit" }, "tx-hash": { "type": "string", "description": "Transaction hash for the token deposit", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "token" }, "processed-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the token deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "asset": { "type": "string", "enum": [ "eth-base/usdt", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/usdc" ], "description": "The token asset of the deposit", "example": "eth-base/usdc" } }, "additionalProperties": false, "required": [ "amount", "coordinates", "tx-hash", "type", "processed-at", "status", "id", "created-at", "asset" ], "title": "Token Deposit" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the USD deposit", "example": "660e8400-e29b-41d4-a716-446655440001" }, "type": { "type": "string", "enum": [ "token", "pix", "manual-fx", "brlv" ], "description": "Type of deposit", "example": "manual-fx" }, "amount": { "type": "string", "format": "decimal", "description": "Amount of the deposit in USD", "example": "100.50" }, "status": { "type": "string", "enum": [ "created", "credited", "voided", "confirmed" ], "description": "Current status of the deposit", "example": "confirmed" }, "coordinates": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "target": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Source and target information for the deposit" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was created" }, "processed-at": { "oneOf": [ { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the deposit was processed" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "id", "type", "amount", "status", "coordinates", "created-at" ], "title": "USD Deposit" } ] } }, "additionalProperties": false, "required": [ "deposit" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get a deposit by ID", "description": "Retrieves a specific deposit by its ID for the authenticated account. Asset can be 'brl', 'usd', 'usdc' or 'usdt'" } }, "/api/v0/nft-transfers": { "get": { "responses": { "200": { "description": "NFT transfers list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the NFT transfer", "example": "660e8400-e29b-41d4-a716-446655440010" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier being transferred", "example": "660e8400-e29b-41d4-a716-446655440010" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" } }, "additionalProperties": false, "required": [ "id", "reward-certificate-id", "source-address", "target-address", "state", "created-at", "state-updated-at" ] }, "description": "List of reward certificate transfers" } }, "additionalProperties": false, "required": [ "transfers" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List reward certificate NFT transfers", "description": "Retrieves a list of reward certificate NFT transfers for the authenticated user." }, "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-address": { "type": "string", "description": "Source wallet address (0x...)", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address (0x...)", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier", "example": "660e8400-e29b-41d4-a716-446655440010" } }, "additionalProperties": false, "required": [ "source-address", "target-address", "reward-certificate-id" ] } } } }, "responses": { "200": { "description": "NFT transfer created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the NFT transfer", "example": "660e8400-e29b-41d4-a716-446655440010" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier being transferred", "example": "660e8400-e29b-41d4-a716-446655440010" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" } }, "additionalProperties": false, "required": [ "id", "reward-certificate-id", "source-address", "target-address", "state", "created-at", "state-updated-at" ], "description": "Details of the created NFT transfer" } }, "additionalProperties": false, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Transfer reward certificate NFT between wallets", "description": "Transfers a reward certificate NFT from a source wallet to a target wallet. Source and target should be EVM wallet addresses (0x...)." } }, "/api/v1/accounts/{account-id}/deposits/pix": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PIX BR Code retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "brl" ], "description": "Asset funded by this PIX deposit", "example": "brl" }, "type": { "type": "string", "enum": [ "pix" ], "description": "Deposit type", "example": "pix" }, "brcode": { "type": "string", "description": "Static PIX BR Code (EMV payload); pay with it directly or render it as a QR code", "example": "00020126360014br.gov.bcb.pix..." }, "qr-code-base64": { "type": "string", "description": "PNG QR code of the BR Code, base64-encoded (no data-uri prefix)", "example": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEs..." } }, "additionalProperties": false, "required": [ "asset", "type", "brcode", "qr-code-base64" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get the PIX deposit QR code", "description": "Returns the static PIX BR Code used to fund the account's BRL balance: the EMV payload string and a base64-encoded PNG of the QR image." } }, "/api/v1/accounts/{account-id}/auto-claims/{schedule-id}/pause": { "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "schedule-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auto-claim schedule paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedule": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ], "description": "The auto-claim schedule" } }, "additionalProperties": false, "required": [ "auto-claim-schedule" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Pause an auto-claim schedule", "description": "Stops a schedule from claiming on its next fires without deleting it; its job stays scheduled so it can be resumed. Requires the auto-claim-rewards capability." } }, "/api/v0/claims/certificates": { "get": { "responses": { "200": { "description": "Claimable certificates retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate unique identifier", "example": "550e8400-e29b-41d4-a716-446655440010" }, "status": { "type": "string", "enum": [ "accruing", "frozen" ], "description": "Current status of the certificate", "example": "accruing" }, "claimable-amount": { "type": "string", "format": "decimal", "description": "Amount currently claimable from this certificate", "example": "150.25" } }, "additionalProperties": false, "required": [ "certificate-id", "status", "claimable-amount" ] }, "description": "List of reward certificates with claimable amounts" }, "total-claimable": { "type": "string", "format": "decimal", "description": "Total claimable amount across all certificates", "example": "350.50" } }, "additionalProperties": false, "required": [ "certificates", "total-claimable" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List claimable reward certificates", "description": "Returns a list of reward certificates with their claimable amounts" } }, "/api/v1/accounts/{account-id}/withdrawals/{id}": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Withdrawal retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440001" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "100.50" }, "method": { "enum": [ "pix" ], "example": "pix" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL PIX withdrawal", "title": "PIX Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440002" }, "asset": { "enum": [ "fiat/brl" ], "example": "fiat/brl" }, "amount": { "type": "string", "format": "decimal", "example": "1500.00" }, "method": { "enum": [ "ted" ], "example": "ted" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "method", "state", "created-at", "state-updated-at" ], "description": "BRL TED withdrawal", "title": "TED Withdrawal" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "660e8400-e29b-41d4-a716-446655440003" }, "asset": { "type": "string", "enum": [ "eth-mainnet/usdc", "eth-base/usdc" ], "description": "Stablecoin asset", "example": "eth-base/usdc" }, "amount": { "type": "string", "format": "decimal", "example": "100.500000000000000000" }, "state": { "type": "string", "enum": [ "created", "rolled-back", "completed", "processing" ], "example": "created" }, "created-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "state-updated-at": { "type": "string", "example": "2025-03-06T10:30:00Z", "format": "date-time" }, "destination-wallet-address": { "type": "string", "description": "Destination wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "tx-hash": { "type": "string", "description": "Transaction hash for completed withdrawal", "example": "0x1234567890abcdef..." } }, "additionalProperties": false, "required": [ "id", "asset", "amount", "state", "created-at", "state-updated-at" ], "description": "Crypto stablecoin withdrawal", "title": "Stablecoin Withdrawal" } ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get a withdrawal by ID", "description": "Retrieves details of a specific withdrawal" } }, "/api/v1/accounts/{account-id}/claims": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Claimable balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "available-balance": { "type": "string", "format": "decimal", "description": "Total available balance that can be claimed", "example": "350.50" } }, "additionalProperties": false, "required": [ "available-balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get claimable balance", "description": "Returns the total available balance that can be claimed" }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Amount to claim from reward certificates", "example": "100.00" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Claim submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Claims request unique identifier", "example": "550e8400-e29b-41d4-a716-446655440003" }, "gross-amount": { "type": "string", "format": "decimal", "description": "Total gross amount of the claims", "example": "100.00" }, "net-amount": { "type": "string", "format": "decimal", "description": "Net amount after taxes and fees", "example": "85.00" }, "tax-amount": { "type": "string", "format": "decimal", "description": "Total tax amount deducted", "example": "15.00" }, "fees": { "type": "string", "format": "decimal", "description": "Processing fees", "example": "0.00" }, "status": { "type": "string", "enum": [ "created", "failed", "completed", "processing", "canceled" ], "description": "Current status of the claims request", "example": "created" }, "updated-at": { "type": "string", "description": "Last update timestamp", "example": "2025-09-30T19:21:57.838913Z" } }, "additionalProperties": false, "required": [ "id", "gross-amount", "net-amount", "tax-amount", "fees", "status", "updated-at" ], "description": "Details of the submitted claim request" } }, "additionalProperties": false, "required": [ "claim" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Submit a claim request", "description": "Submits a claim for a specified amount from reward certificates" } }, "/api/v0/assets/{asset}/balance": { "get": { "parameters": [ { "in": "path", "name": "asset", "required": true, "schema": { "type": "string", "enum": [ "usdc", "usdt", "brl", "brly", "usd", "brlv", "wbrly" ] } } ], "responses": { "200": { "description": "Asset balance retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "object", "properties": { "running-balance": { "type": "string", "format": "decimal", "description": "Balance rendered at the asset's decimal scale (brl=2, usdc=6, brlv=18).", "example": "0.000000000000000000" } }, "additionalProperties": false, "required": [ "running-balance" ] } }, "additionalProperties": false, "required": [ "balance" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Get balance by asset", "description": "Retrieves the authenticated account's balance for a given asset. The balance is returned at the asset's decimal scale (brl=2, usdc=6, brlv=18)." } }, "/api/v1/accounts/{account-id}/auto-claims": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auto-claim schedules retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedules": { "type": "array", "items": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ] }, "description": "Auto-claim schedules for the account" } }, "additionalProperties": false, "required": [ "auto-claim-schedules" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List auto-claim schedules", "description": "Returns the account's recurring auto-claim schedules (account- and wallet-scoped). Requires the auto-claim-rewards capability." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "max-amount": { "oneOf": [ { "type": "string" }, { "type": "number", "format": "double" } ], "description": "Claim up to this amount each run; if less is available, claims what's available", "example": "100.00" }, "cron": { "type": "string", "description": "UNIX cron expression (5 fields). Must fire at most once per day", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "description": "Destination asset: 'brl' for bank transfer or 'brlv' for on-chain tokens", "example": "brlv", "enum": [ "brl", "brlv" ] } }, "additionalProperties": false, "required": [ "max-amount", "cron" ] } } } }, "responses": { "200": { "description": "Auto-claim schedule created", "content": { "application/json": { "schema": { "type": "object", "properties": { "auto-claim-schedule": { "type": "object", "properties": { "last-run-at": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Timestamp of the last run, or null" }, "scope": { "type": "string", "enum": [ "wallet", "account" ], "description": "Whether the schedule claims account-wide or for a single wallet" }, "cron": { "type": "string", "description": "UNIX cron expression", "example": "0 9 * * *" }, "target-asset-code": { "type": "string", "enum": [ "brl", "brlv" ], "description": "Destination asset for each claim" }, "max-amount": { "type": "string", "format": "decimal", "description": "Maximum amount claimed each run" }, "id": { "type": "string", "format": "uuid", "description": "Auto-claim schedule unique identifier" }, "created-at": { "type": "string", "description": "Creation timestamp" }, "enabled": { "type": "boolean", "description": "Whether the schedule is active" }, "wallet-address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target wallet address when scope is 'wallet', otherwise null" } }, "additionalProperties": false, "required": [ "last-run-at", "scope", "cron", "target-asset-code", "max-amount", "id", "created-at", "enabled", "wallet-address" ], "description": "The auto-claim schedule" } }, "additionalProperties": false, "required": [ "auto-claim-schedule" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create an account-wide auto-claim schedule", "description": "Schedules a recurring claim of up to the given amount on a UNIX cron (at least daily) across all of the account's reward certificates. Requires the auto-claim-rewards capability." } }, "/api/v1/accounts/{account-id}/nft-transfers": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "NFT transfers list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the NFT transfer", "example": "660e8400-e29b-41d4-a716-446655440010" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier being transferred", "example": "660e8400-e29b-41d4-a716-446655440010" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" } }, "additionalProperties": false, "required": [ "id", "reward-certificate-id", "source-address", "target-address", "state", "created-at", "state-updated-at" ] }, "description": "List of reward certificate transfers" } }, "additionalProperties": false, "required": [ "transfers" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List reward certificate NFT transfers", "description": "Retrieves a list of reward certificate NFT transfers for the authenticated user." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source-address": { "type": "string", "description": "Source wallet address (0x...)", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address (0x...)", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier", "example": "660e8400-e29b-41d4-a716-446655440010" } }, "additionalProperties": false, "required": [ "source-address", "target-address", "reward-certificate-id" ] } } } }, "responses": { "200": { "description": "NFT transfer created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the NFT transfer", "example": "660e8400-e29b-41d4-a716-446655440010" }, "reward-certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate identifier being transferred", "example": "660e8400-e29b-41d4-a716-446655440010" }, "source-address": { "type": "string", "description": "Source wallet address", "example": "0xabcdef1234567890abcdef1234567890abcdef12" }, "target-address": { "type": "string", "description": "Target wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "state": { "type": "string", "enum": [ "created", "failed", "completed", "pending" ], "description": "Current state of the transfer", "example": "created" }, "created-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer was created" }, "state-updated-at": { "type": "string", "example": "2024-01-15T10:30:00Z", "format": "date-time", "description": "ISO 8601 timestamp when the transfer state was last updated" } }, "additionalProperties": false, "required": [ "id", "reward-certificate-id", "source-address", "target-address", "state", "created-at", "state-updated-at" ], "description": "Details of the created NFT transfer" } }, "additionalProperties": false, "required": [ "transfer" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Transfer reward certificate NFT between wallets", "description": "Transfers a reward certificate NFT from a source wallet to a target wallet. Source and target should be EVM wallet addresses (0x...)." } }, "/api/v0/wallets/{wallet-address}/claims/certificates": { "get": { "parameters": [ { "in": "path", "name": "wallet-address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claimable certificates retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "certificate-id": { "type": "string", "format": "uuid", "description": "Reward certificate unique identifier", "example": "550e8400-e29b-41d4-a716-446655440010" }, "status": { "type": "string", "enum": [ "accruing", "frozen" ], "description": "Current status of the certificate", "example": "accruing" }, "claimable-amount": { "type": "string", "format": "decimal", "description": "Amount currently claimable from this certificate", "example": "150.25" } }, "additionalProperties": false, "required": [ "certificate-id", "status", "claimable-amount" ] }, "description": "List of reward certificates with claimable amounts" }, "total-claimable": { "type": "string", "format": "decimal", "description": "Total claimable amount across all certificates", "example": "350.50" } }, "additionalProperties": false, "required": [ "certificates", "total-claimable" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List claimable reward certificates for a wallet", "description": "Returns the reward certificates with their claimable amounts for the given wallet address." } }, "/api/v1/accounts/{account-id}/wallets": { "get": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "assets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "example": [ "eth-base/brlv", "eth-base/wbrly", "eth-base/eth-mainnet" ] }, "description": "Filter wallets by asset types" }, { "in": "query", "name": "addresses", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "0x1234567890abcdef1234567890abcdef12345678" ] }, "description": "Filter wallets by specific addresses" } ], "responses": { "200": { "description": "Wallets list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the wallet", "example": "My Trading Wallet" }, "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "assets": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "List of assets supported by this wallet", "example": [ "eth-base/brlv", "eth-base/wbrly" ] }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata associated with this wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet is visible in the UI", "example": true } }, "additionalProperties": false, "required": [ "name", "address", "assets", "ui-enabled" ] }, "description": "List of wallets" } }, "additionalProperties": false, "required": [ "wallets" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "List wallets", "description": "Returns a list of wallets. Can be filtered by assets and/or addresses." }, "post": { "parameters": [ { "in": "path", "name": "account-id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet-name": { "type": "string", "description": "Name for the new wallet", "example": "My Trading Wallet" }, "chain": { "type": "string", "enum": [ "tempo", "eth-mainnet", "eth-base" ], "description": "Blockchain that this wallet will be supported on", "example": "eth-base" }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Custom metadata to associate with the wallet", "example": { "label": "treasury" } }, "ui-enabled": { "type": "boolean", "description": "Whether this wallet should be visible in the UI (defaults to false)", "example": false } }, "additionalProperties": false, "required": [ "wallet-name", "chain" ] } } } }, "responses": { "200": { "description": "Wallet created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum wallet address", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "assets": { "type": "array", "items": { "type": "string", "enum": [ "tempo/brlv", "eth-base/brlv", "eth-mainnet/brlv", "fiat/brl", "eth-base/usdt", "fiat/usd", "eth-mainnet/usdt", "eth-mainnet/usdc", "eth-base/wbrly", "eth-base/usdc", "eth-base/brly" ] }, "description": "List of supported assets for this wallet", "example": [ "eth-base/brlv", "eth-base/wbrly" ] } }, "additionalProperties": false, "required": [ "address", "assets" ] } }, "additionalProperties": false, "required": [ "wallet" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Bad request error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Forbidden - Access denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Forbidden access error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Resource not found error details" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "message", "code" ], "description": "Validation error details" } }, "additionalProperties": false, "required": [ "error" ] } } } } }, "summary": "Create a new wallet", "description": "Creates a new wallet with the specified name and default assets (BRLV and wBRLY if applicable)." } } }, "webhooks": { "deposit-processed": { "post": { "summary": "Deposit Processed", "description": "Triggered when a deposit is credited to the account. This covers fiat deposits (BRL via PIX or TED) and crypto deposits. A token (USDC, USDT, or BRLV) transferred into one of the account's wallets is also treated as a deposit, and carries the crypto payload variant with the asset and on-chain addresses.", "operationId": "depositProcessed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "deposit-processed" ] }, "payload": { "oneOf": [ { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "title": "Amount" }, "tx-hash": { "type": "string", "title": "Tx Hash" }, "deposit-type": { "type": "string", "title": "Deposit Type" }, "source-address": { "type": "string", "title": "Source Address" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "status": { "type": "string", "title": "Status" }, "target-address": { "type": "string", "title": "Target Address" }, "deposit-id": { "type": "string", "format": "uuid", "title": "Deposit Id" }, "created-at": { "type": "string", "title": "Created At" }, "asset": { "type": "string", "title": "Asset" } }, "additionalProperties": false, "required": [ "amount", "deposit-type", "source-address", "account-id", "status", "target-address", "deposit-id", "created-at", "asset" ] }, { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "title": "Amount" }, "source-legal-name": { "type": "string", "title": "Source Legal Name" }, "source-tax-id": { "type": "string", "title": "Source Tax Id" }, "deposit-type": { "type": "string", "title": "Deposit Type" }, "source-account-number": { "type": "string", "title": "Source Account Number" }, "source-bank-code": { "type": "string", "title": "Source Bank Code" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "processed-at": { "type": "string", "title": "Processed At" }, "status": { "type": "string", "title": "Status" }, "deposit-id": { "type": "string", "format": "uuid", "title": "Deposit Id" }, "source-branch-code": { "type": "string", "title": "Source Branch Code" } }, "additionalProperties": false, "required": [ "amount", "source-legal-name", "source-tax-id", "deposit-type", "source-account-number", "source-bank-code", "account-id", "processed-at", "status", "deposit-id", "source-branch-code" ] } ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440010", "event-type": "deposit-processed", "payload": { "amount": "1000.00", "source-legal-name": "João Silva", "source-tax-id": "12345678900", "deposit-type": "pix", "source-account-number": "12345", "source-bank-code": "001", "account-id": "660e8400-e29b-41d4-a716-446655440001", "processed-at": "2024-01-15T10:30:00Z", "status": "processed", "deposit-id": "660e8400-e29b-41d4-a716-446655440000", "source-branch-code": "0001" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "order-completed": { "post": { "summary": "Order Completed", "description": "Triggered when a currency conversion order has been successfully completed.", "operationId": "orderCompleted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "order-completed" ] }, "payload": { "type": "object", "properties": { "tx-timestamp": { "type": "string", "title": "Tx Timestamp" }, "tx-hash": { "type": "string", "title": "Tx Hash" }, "effective-rate": { "type": "string", "format": "decimal", "title": "Effective Rate" }, "target-asset": { "type": "string", "title": "Target Asset" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "created-by": { "type": "string", "format": "uuid", "title": "Created By" }, "order-id": { "type": "string", "format": "uuid", "title": "Order Id" }, "source-asset": { "type": "string", "title": "Source Asset" }, "source-amount": { "type": "string", "format": "decimal", "title": "Source Amount" }, "completed-at": { "type": "string", "title": "Completed At" }, "source-wallet-address": { "type": "string", "title": "Source Wallet Address" }, "target-wallet-address": { "type": "string", "title": "Target Wallet Address" }, "target-amount": { "type": "string", "format": "decimal", "title": "Target Amount" } }, "additionalProperties": false, "required": [ "effective-rate", "target-asset", "account-id", "created-by", "order-id", "source-asset", "source-amount", "completed-at", "target-amount" ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440011", "event-type": "order-completed", "payload": { "tx-hash": "0xabc123...", "effective-rate": "0.995", "target-asset": "eth-base/brlv", "account-id": "660e8400-e29b-41d4-a716-446655440001", "created-by": "660e8400-e29b-41d4-a716-446655440003", "order-id": "660e8400-e29b-41d4-a716-446655440002", "source-asset": "fiat/brl", "source-amount": "100.00", "completed-at": "2024-01-15T10:35:00Z", "source-wallet-address": "0x1234567890abcdef1234567890abcdef12345678", "target-wallet-address": "0xabcdef1234567890abcdef1234567890abcdef12", "target-amount": "99.50" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "token-transfer-completed": { "post": { "summary": "Token Transfer Completed", "description": "Triggered when a token transfer sent from one of the account's wallets completes on-chain. A transfer moves tokens out of one of the account's wallets to a destination wallet.", "operationId": "tokenTransferCompleted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "token-transfer-completed" ] }, "payload": { "type": "object", "properties": { "amount": { "type": "string", "format": "decimal", "title": "Amount" }, "transfer-id": { "type": "string", "format": "uuid", "title": "Transfer Id" }, "tx-hash": { "type": "string", "title": "Tx Hash" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "created-by": { "type": "string", "format": "uuid", "title": "Created By" }, "completed-at": { "type": "string", "title": "Completed At" }, "source-wallet-address": { "type": "string", "title": "Source Wallet Address" }, "target-wallet-address": { "type": "string", "title": "Target Wallet Address" }, "asset": { "type": "string", "title": "Asset" } }, "additionalProperties": false, "required": [ "amount", "transfer-id", "account-id", "created-by", "completed-at", "asset" ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440012", "event-type": "token-transfer-completed", "payload": { "amount": "50.00", "transfer-id": "660e8400-e29b-41d4-a716-446655440004", "tx-hash": "0xdef456...", "account-id": "660e8400-e29b-41d4-a716-446655440001", "created-by": "660e8400-e29b-41d4-a716-446655440003", "completed-at": "2024-01-15T10:40:00Z", "source-wallet-address": "0x1234567890abcdef1234567890abcdef12345678", "target-wallet-address": "0xabcdef1234567890abcdef1234567890abcdef12", "asset": "eth-base/brlv" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "withdraw-completed": { "post": { "summary": "Withdrawal Completed", "description": "Triggered when a withdrawal (BRL PIX/TED or token) has been successfully processed and sent.", "operationId": "withdrawCompleted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "withdraw-completed" ] }, "payload": { "oneOf": [ { "type": "object", "properties": { "withdraw-id": { "type": "string", "format": "uuid", "title": "Withdraw Id" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "created-by": { "type": "string", "format": "uuid", "title": "Created By" }, "amount": { "type": "string", "title": "Amount" }, "asset": { "type": "string", "title": "Asset" }, "processed-at": { "type": "string", "title": "Processed At" }, "destination-wallet-address": { "type": "string", "title": "Destination Wallet Address" }, "tx-hash": { "type": "string", "title": "Tx Hash" } }, "additionalProperties": false, "required": [ "withdraw-id", "account-id", "created-by", "amount", "asset", "processed-at" ] }, { "type": "object", "properties": { "amount": { "type": "string", "title": "Amount" }, "target-account-number": { "type": "string", "title": "Target Account Number" }, "withdraw-id": { "type": "string", "format": "uuid", "title": "Withdraw Id" }, "target-legal-name": { "type": "string", "title": "Target Legal Name" }, "target-tax-id": { "type": "string", "title": "Target Tax Id" }, "target-branch-code": { "type": "string", "title": "Target Branch Code" }, "method": { "type": "string", "enum": [ "ted", "pix" ], "title": "Method" }, "target-bank-code": { "type": "string", "title": "Target Bank Code" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "processed-at": { "type": "string", "title": "Processed At" }, "created-by": { "type": "string", "format": "uuid", "title": "Created By" }, "asset": { "type": "string", "enum": [ "fiat/brl" ], "title": "Asset" } }, "additionalProperties": false, "required": [ "amount", "target-account-number", "withdraw-id", "target-legal-name", "target-tax-id", "target-branch-code", "method", "target-bank-code", "account-id", "processed-at", "created-by", "asset" ] } ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440013", "event-type": "withdraw-completed", "payload": { "amount": "500.00", "target-account-number": "54321", "withdraw-id": "660e8400-e29b-41d4-a716-446655440007", "target-legal-name": "Maria Santos", "target-tax-id": "98765432100", "target-branch-code": "0001", "method": "pix", "target-bank-code": "12345678", "account-id": "660e8400-e29b-41d4-a716-446655440001", "processed-at": "2024-01-15T10:45:00Z", "created-by": "660e8400-e29b-41d4-a716-446655440003", "asset": "fiat/brl" } } }, "examples": { "brl-pix": { "summary": "BRL PIX Withdrawal", "value": { "event-id": "660e8400-e29b-41d4-a716-446655440013", "event-type": "withdraw-completed", "payload": { "amount": "500.00", "target-account-number": "54321", "withdraw-id": "660e8400-e29b-41d4-a716-446655440007", "target-legal-name": "Maria Santos", "target-tax-id": "98765432100", "target-branch-code": "0001", "method": "pix", "target-bank-code": "12345678", "account-id": "660e8400-e29b-41d4-a716-446655440001", "processed-at": "2024-01-15T10:45:00Z", "created-by": "660e8400-e29b-41d4-a716-446655440003", "asset": "fiat/brl" } } }, "brl-ted": { "summary": "BRL TED Withdrawal", "value": { "event-id": "660e8400-e29b-41d4-a716-446655440015", "event-type": "withdraw-completed", "payload": { "amount": "1500.00", "target-account-number": "98765", "withdraw-id": "660e8400-e29b-41d4-a716-446655440009", "target-legal-name": "João Silva", "target-tax-id": "12345678900", "target-branch-code": "0001", "method": "ted", "target-bank-code": "341", "account-id": "660e8400-e29b-41d4-a716-446655440001", "processed-at": "2024-01-15T11:00:00Z", "created-by": "660e8400-e29b-41d4-a716-446655440003", "asset": "fiat/brl" } } }, "token-usdc": { "summary": "Token Withdrawal (USDC)", "value": { "event-id": "770e8400-e29b-41d4-a716-446655440014", "event-type": "withdraw-completed", "payload": { "withdraw-id": "770e8400-e29b-41d4-a716-446655440008", "account-id": "660e8400-e29b-41d4-a716-446655440001", "created-by": "660e8400-e29b-41d4-a716-446655440003", "amount": "100.500000000000000000", "asset": "eth-base/usdc", "destination-wallet-address": "0x69fE761eE92bdD3F37a1Be13820405Da9CfF23ef", "tx-hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "processed-at": "2024-01-15T10:45:00Z" } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "claim-completed": { "post": { "summary": "Claim Completed", "description": "Triggered when a yield claim has been successfully processed and tokens have been deposited.", "operationId": "claimCompleted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "claim-completed" ] }, "payload": { "type": "object", "properties": { "claim-id": { "type": "string", "format": "uuid", "title": "Claim Id" }, "claim-tx-hash": { "type": "string", "title": "Claim Tx Hash" }, "deposit-tx-hash": { "type": "string", "title": "Deposit Tx Hash" }, "account-id": { "type": "string", "format": "uuid", "title": "Account Id" }, "net-amount": { "type": "string", "format": "decimal", "title": "Net Amount" }, "gross-amount": { "type": "string", "format": "decimal", "title": "Gross Amount" }, "completed-at": { "type": "string", "title": "Completed At" }, "fees": { "type": "string", "format": "decimal", "title": "Fees" }, "tax-amount": { "type": "string", "format": "decimal", "title": "Tax Amount" } }, "additionalProperties": false, "required": [ "claim-id", "claim-tx-hash", "deposit-tx-hash", "account-id", "net-amount", "gross-amount", "completed-at", "fees", "tax-amount" ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440014", "event-type": "claim-completed", "payload": { "claim-id": "660e8400-e29b-41d4-a716-446655440008", "claim-tx-hash": "0xghi789...", "deposit-tx-hash": "0xjkl012...", "account-id": "660e8400-e29b-41d4-a716-446655440001", "net-amount": "840.00", "gross-amount": "1000.00", "completed-at": "2024-01-15T10:50:00Z", "fees": "10.00", "tax-amount": "150.00" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "account-approved": { "post": { "summary": "Sub-account Approved", "description": "Triggered when a partner-initiated sub-account creation request clears compliance and the sub-account has been provisioned and activated. Fires on the parent (partner) account's subscriptions.", "operationId": "accountApproved", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "account-approved" ] }, "payload": { "type": "object", "properties": { "subaccount-id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "status": { "type": "string", "enum": [ "active" ], "title": "Status" }, "completed-at": { "type": "string", "title": "Completed At" } }, "additionalProperties": false, "required": [ "subaccount-id", "status", "completed-at" ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440015", "event-type": "account-approved", "payload": { "subaccount-id": "660e8400-e29b-41d4-a716-446655440020", "status": "active", "completed-at": "2024-01-15T10:55:00Z" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "account-rejected": { "post": { "summary": "Sub-account Rejected", "description": "Triggered when a partner-initiated sub-account creation request is not approved (rejected, expired, or cancelled). The reason is intentionally opaque and never discloses sanctions/KYC details. Fires on the parent (partner) account's subscriptions.", "operationId": "accountRejected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event-id", "event-type", "payload" ], "properties": { "event-id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook event" }, "event-type": { "type": "string", "enum": [ "account-rejected" ] }, "payload": { "type": "object", "properties": { "subaccount-id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "status": { "type": "string", "enum": [ "rejected" ], "title": "Status" }, "reason": { "type": "string", "enum": [ "compliance" ], "title": "Reason" }, "rejected-at": { "type": "string", "title": "Rejected At" } }, "additionalProperties": false, "required": [ "subaccount-id", "status", "reason", "rejected-at" ] } }, "example": { "event-id": "660e8400-e29b-41d4-a716-446655440016", "event-type": "account-rejected", "payload": { "subaccount-id": "660e8400-e29b-41d4-a716-446655440021", "status": "rejected", "reason": "compliance", "rejected-at": "2024-01-15T11:05:00Z" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } }, "components": { "securitySchemes": { "JwtAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT-based authentication." }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your account API Key" }, "signature": { "type": "apiKey", "in": "header", "name": "X-Crown-Signature", "description": "HMAC-SHA256 signature of the request body using your webhook secret. Verify this signature to ensure the webhook is from Crown." } } }, "x-webhook-security": { "note": "All webhook requests include an X-Crown-Signature header containing an HMAC-SHA256 signature of the request body. Use your webhook secret (provided when registering the webhook) to verify the signature and ensure the request is authentic.", "algorithm": "HMAC-SHA256", "header": "X-Crown-Signature", "verification-steps": [ "1. Extract the X-Crown-Signature header from the request", "2. Compute HMAC-SHA256 of the raw request body using your webhook secret", "3. Compare the computed signature with the header value", "4. Only process the webhook if signatures match" ], "example-code": { "node-js": "const crypto = require('crypto');\nconst signature = crypto.createHmac('sha256', webhookSecret)\n .update(JSON.stringify(requestBody))\n .digest('hex');\nconst isValid = signature === req.headers['x-crown-signature'];", "python": "import hmac\nimport hashlib\nimport json\n\nsignature = hmac.new(\n webhook_secret.encode('utf-8'),\n json.dumps(request_body).encode('utf-8'),\n hashlib.sha256\n).hexdigest()\nis_valid = signature == request.headers['x-crown-signature']" } } }