BRL Accounts API
The Accounts API from BRL — 27 operation(s) for accounts.
OpenAPI Specification
openapi: 3.1.0
info:
title: Crown API & Webhooks Accounts 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: Accounts
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.
tags:
- Accounts
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.
tags:
- Accounts
/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.
tags:
- Accounts
/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
# --- truncated at 32 KB (301 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brl/refs/heads/main/openapi/brl-accounts-api-openapi.yml