openapi: 3.1.0 info: title: Crown API & Webhooks Accounts Orders API version: 1.0.0 description: 'Open API 3 docs for Crown API Webhook 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 tags: - name: Orders paths: /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 tags: - Orders 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. tags: - Orders /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 tags: - Orders 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']"