BRL Orders API
The Orders API from BRL — 2 operation(s) for orders.
OpenAPI Specification
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 th
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brl/refs/heads/main/openapi/brl-orders-api-openapi.yml