Available Combinations

How It Works

Each combination defines a specific type of transaction. The quote calculates the price and fees, while the ticket executes the operation.

Elements of a Combination

Input (What you provide) - The source of funds
Output (What you receive) - The destination of funds
Quote - Parameters to get the price
Ticket - Specific fields to execute

Modifying for Different Results

To change the amount: Use inputAmount or outputAmount in the quote To change the currency: Modify inputCurrency and outputCurrency To change the network: Adjust inputPaymentMethod and outputPaymentMethod To change the method: Choose between PERMIT or TRANSFER (for blockchain operations only)

PIX to Crypto

BRL → BRLA/USDC/USDT/EURC

Input: R$ via PIX Output: Tokens on blockchain

info

You can register frequently used wallets in Beneficiary Wallets to avoid entering wallet details every time. Simply use the beneficiaryWalletId instead of providing wallet details directly.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRL`	The currency you are paying with
`inputPaymentMethod`	`PIX`	The payment method you are using
`inputAmount`	`100`	The amount you want to pay
`outputCurrency`	`BRLA`	The currency you want to receive
`outputPaymentMethod`	`INTERNAL`	The blockchain where you want to receive tokens

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "uuid-of-registered-wallet"
  },
  "customDuration": 600
}

Request Parameters

Parameter	Type	Description
`beneficiaryWalletId`	string (UUID)	Registered wallet ID to receive tokens
`customDuration`	integer	Operation expiration time in seconds. Minimum 300 (5 minutes). For currency conversion operations (inputCurrency ≠ outputCurrency): max 600 (10 minutes). For same currency operations (inputCurrency = outputCurrency): max 259200 (72 hours).

Ticket Response

{
  "brCode": "00020126580014br.gov.bcb.pix...",
  "expiration": "2025-03-11T16:06:42.638410717Z",
  "id": "00000000-0000-0000-0000-000000000000"
}

Response Fields

Field	Type	Description
`brCode`	string	PIX QR code for payment - user must pay this
`expiration`	timestamp	ISO 8601 expiration time for the brCode

Result: System returns a brCode for PIX payment. After payment, tokens are credited to the specified wallet.

info

Fiat currencies can have a maximum of 2 decimal places, while blockchain currencies can have up to 6 decimal places.

Crypto to PIX

BRLA/USDC/USDT/EURC → BRL

Input: Tokens from blockchain Output: R$ via PIX

info

You can register frequently used bank accounts in Beneficiary Bank Accounts to avoid entering account details every time. Simply use the beneficiaryBrlBankAccountId instead of providing account details directly.

Option 1: Using Registered Beneficiary Account

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`BRL`	The currency you want to receive
`outputPaymentMethod`	`PIX`	The payment method for receiving funds
`blockchainSendMethod`	string	Defines the blockchain transaction type. Can be `TRANSFER` or `PERMIT`. Required for blockchain inputs.

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBrlPixOutput": {
    "beneficiaryBrlBankAccountId": "uuid-of-registered-account",
    "pixMessage": "optional PIX message"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryBrlBankAccountId`	string (UUID)	Registered BRL bank account ID for receiving PIX
`pixMessage`	string (optional)	Optional message to include in PIX transaction

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Option 2: Using PIX Key

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`BRL`	The currency you want to receive
`outputPaymentMethod`	`PIX`	The payment method for receiving funds
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBrlPixOutput": {
    "pixKey": "50.224.164/0001-70",
    "pixMessage": "optional PIX message"
  }
}

Request Parameters

Parameter	Type	Description
`pixKey`	string	PIX key for receiving funds (CPF, CNPJ, email, phone, or random key)
`pixMessage`	string (optional)	Optional message to include in PIX transaction

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Option 3: Using Full Bank Account Details

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`BRL`	The currency you want to receive
`outputPaymentMethod`	`PIX`	The payment method for receiving funds
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "pixMessage": "optional PIX message",
  "ticketBrlPixOutput": {
    "userName": "John Doe",
    "bankCode": "260",
    "branchCode": "0001",
    "accountNumber": "12345678",
    "accountType": "checking",
    "taxId": "123.456.789-00"
  }
}

Request Parameters

Parameter	Type	Description
`userName`	string	Full name of the account holder
`bankCode`	string	Bank code (3 or 8 digits)
`branchCode`	string	Branch code of the bank account
`accountNumber`	string	Account number
`accountType`	string	Account type: checking, payment, savings, or salary
`taxId`	string	CPF or CNPJ of the account holder
`pixMessage`	string (optional)	Optional message to include in PIX transaction

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

warning

Choose only one option: either beneficiaryBrlBankAccountId, pixKey, full bank account details, or brCode — not multiple options together.

Result: PIX is sent automatically to the specified bank account, PIX key, or brCode is generated for payment.

info

Just like for input, fiat currencies can have a maximum of 2 decimal places, while blockchain currencies can have up to 6 decimal places.

Option 4: Using brCode

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	Payment method (subaccount's internal balance)
`inputAmount`	`8.550804`	The amount you want to convert
`outputCurrency`	`BRL`	Currency in which the brCode will be paid
`outputPaymentMethod`	`PIX-BRCODE`	Payment method for the payout (via PIX brCode)
`inputThirdParty`	`false`	Indicates funds come from the subaccount itself
`outputThirdParty`	`false`	Set to true if the brCode is paid to a third party
`blockchainSendMethod`	`PERMIT`	Specifies that the transfer is automatically handled
`outputBrCode`	`00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/...`	The brCode that the user will pay

Ticket Request

{
  "quoteToken": "eyJ...",
  "externalId": "your-reference-id"
}

Request Parameters

Parameter	Type	Description
`externalId`	string	Your reference ID for tracking this transaction

Ticket Response

{
  "id": "a14d6b53-e573-4e68-b34a-2a1b717eb448"
}

warning

Some BrCodes do not have a specified value. In such cases, provide either the inputAmount or the outputAmount—only one amount is allowed, so do not include both.

USD to Crypto

USD → USDC/USDT

Input: $ via WIRE/ACH Output: Tokens on blockchain

info

The tokens are delivered on-chain, so register the destination wallet in Beneficiary Wallets and pass its beneficiaryWalletId (instead of a bank account). See Beneficiary Wallets.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USD`	The currency you are paying with
`inputPaymentMethod`	`WIRE`	The payment method you are using
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`USDC`	The currency you want to receive
`outputPaymentMethod`	`POLYGON`	The blockchain where you want to receive the tokens (e.g. `POLYGON`, `ETHEREUM`, `BASE`)

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "uuid-of-registered-wallet"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryWalletId`	string (UUID)	Registered wallet ID (from Beneficiary Wallets) that will receive the tokens

Ticket Response

{
  "id": "bc4a2582-0204-4827-9ddf-3a77ea59a0d1",
  "usdDepositInstructions": {
    "accountHolderName": "BRLA Digital LTDA",
    "bankAccountNumber": "218939188578",
    "bankRoutingNumber": "101019644",
    "accountType": "CHECKING",
    "bankName": "Partner Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "depositMessage": "BRGWSSY9E6WEKTS4RTJ6",
    "paymentRail": "WIRE"
  }
}

Response Fields

Field	Type	Description
`usdDepositInstructions.accountHolderName`	string	Account holder name to send USD to
`usdDepositInstructions.bankAccountNumber`	string	Bank account number for deposit
`usdDepositInstructions.bankRoutingNumber`	string	ABA routing number
`usdDepositInstructions.accountType`	string	Type of account (e.g., CHECKING)
`usdDepositInstructions.bankName`	string	Name of the receiving bank
`usdDepositInstructions.bankAddress`	string	Physical address of the bank
`usdDepositInstructions.depositMessage`	string	Reference message for the deposit
`usdDepositInstructions.paymentRail`	string	Payment method used (WIRE or ACH)

Result: System returns WIRE deposit instructions. After bank confirmation, tokens are credited.

tip

For USD input transactions, you benefit from direct 1:1 conversion to stablecoins without exchange rate fluctuations, making it ideal for preserving value when moving from fiat to crypto.

USD Payment Methods Characteristics

When working with USD transactions, it's important to understand the differences between the available payment methods and how currency conversion works.

Payment Method Differences

WIRE Transfers:

Faster processing - Typically settled within hours
Higher fees - More expensive due to the expedited nature
Best for: Urgent transfers or large amounts where speed is prioritized

ACH Transfers:

Lower fees - More cost-effective option
Slower settlement - Can take 1-3 business days to process
Best for: Regular transfers where cost efficiency is more important than speed

Currency Conversion Rules

For Input Transactions (Deposits):

No currency exchange - USD deposits maintain their value
1:1 conversion to crypto - USD converts directly to stablecoins at a 1:1 ratio
Example: Depositing $100 USD will give you $100 worth of USDC/USDT

For Output Transactions (Withdrawals):

Normal exchange rates apply - Standard market rates and fees
Currency conversion - When converting from other currencies to USD

Crypto to USD

USDC/USDT → USD

Input: Tokens from blockchain Output: $ via WIRE/ACH

info

You can register frequently used USD bank accounts in Beneficiary Bank Accounts to avoid entering account details every time. Simply use the beneficiaryUsdBankAccountId instead of providing account details directly.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`USD`	The currency you want to receive
`outputPaymentMethod`	`WIRE`	The payment method for receiving funds
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketUsdOutput": {
    "beneficiaryUsdBankAccountId": "uuid-of-usd-account",
    "wireMessage": "Payment reference"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryUsdBankAccountId`	string (UUID)	Registered USD bank account ID to receive WIRE
`wireMessage`	string (optional)	Reference message for the WIRE transfer

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: WIRE is sent automatically to the bank account.

tip

For USD input transactions, you benefit from direct 1:1 conversion to stablecoins without exchange rate fluctuations, making it ideal for preserving value when moving from fiat to crypto.

USD Output Operations

Crypto → USD (WIRE Transfer)

Input: Tokens from blockchain Output: $ via WIRE

info

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketUsdOutput": {
    "beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000",
    "wireMessage": "Payment for services"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryUsdBankAccountId`	string (UUID)	Registered USD bank account ID to receive WIRE
`wireMessage`	string (optional)	Reference message for the WIRE transfer

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: WIRE is sent automatically to the specified bank account.

Crypto → USD (ACH Transfer)

Input: Tokens from blockchain Output: $ via ACH

info

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketUsdOutput": {
    "beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000",
    "achReference": "REF123456"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryUsdBankAccountId`	string (UUID)	Registered USD bank account ID to receive ACH
`achReference`	string (optional)	Reference code for the ACH transfer

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: ACH transfer is sent automatically to the specified bank account.

EUR Output Operations

Crypto → EUR (SEPA Transfer)

Input: EURC tokens from blockchain Output: € via SEPA

info

You can register frequently used EUR bank accounts in Beneficiary Bank Accounts to avoid entering account details every time. Simply use the beneficiaryEurBankAccountId instead of providing account details directly.

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketEurSepaOutput": {
    "beneficiaryEurBankAccountId": "00000000-0000-0000-0000-000000000000",
    "sepaReference": "Payment reference"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryEurBankAccountId`	string (UUID)	Registered EUR bank account ID to receive SEPA transfer
`sepaReference`	string (optional)	Reference code for the SEPA transfer

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: SEPA transfer is sent automatically to the bank account.

EUR to Crypto

EUR → EURC

Input: € via SEPA Output: Tokens on blockchain

info

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`EUR`	The currency you are paying with
`inputPaymentMethod`	`SEPA`	The payment method you are using
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`EURC`	The currency you want to receive
`outputPaymentMethod`	`INTERNAL`	The blockchain where you want to receive tokens

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketEurSepaOutput": {
    "beneficiaryEurBankAccountId": "uuid-of-eur-account"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryEurBankAccountId`	string (UUID)	Registered EUR bank account ID to receive SEPA deposit instructions

Ticket Response

{
  "id": "cedc708c-3430-49c7-b100-451910e85967",
  "eurDepositInstructions": {
    "bankBeneficiaryName": "JANE",
    "iban": "IE33MODR99035504937309",
    "bic": "MODRIE22XXX",
    "bankName": "Partner Bank, Ireland Branch",
    "depositMessage": "BRGGM5DASSH96PRPYKZJ",
    "paymentRail": "SEPA",
    "currency": "EUR"
  }
}

Response Fields

Field	Type	Description
`eurDepositInstructions.bankBeneficiaryName`	string	Account holder name to send EUR to
`eurDepositInstructions.iban`	string	IBAN for the receiving bank account
`eurDepositInstructions.bic`	string	BIC (SWIFT) code for SEPA transfer
`eurDepositInstructions.bankName`	string	Name of the receiving bank
`eurDepositInstructions.depositMessage`	string	Reference message for the deposit
`eurDepositInstructions.paymentRail`	string	Payment method used (SEPA)
`eurDepositInstructions.currency`	string	Currency code (EUR)

Result: System returns SEPA deposit instructions. After bank confirmation, EURC tokens are credited.

tip

For EUR input transactions, you benefit from direct 1:1 conversion to EURC without exchange rate fluctuations, making it ideal for preserving value when moving from fiat to crypto.

EUR Payment Methods Characteristics

Currency Conversion Rules

For Input Transactions (Deposits):

No currency exchange - EUR deposits maintain their value
1:1 conversion to crypto - EUR converts directly to stablecoins at a 1:1 ratio
Example: Depositing €100 EUR will give you €100 worth of EURC

For Output Transactions (Withdrawals):

Normal exchange rates apply - Standard market rates and fees
Currency conversion - When converting from other currencies to EURC

Crypto to EUR

EURC → EUR

Input: EURC tokens from blockchain Output: € via SEPA

info

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`EURC`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`EUR`	The currency you want to receive
`outputPaymentMethod`	`SEPA`	The payment method for receiving funds
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketEurSepaOutput": {
    "beneficiaryEurBankAccountId": "uuid-of-eur-account",
    "sepaReference": "Payment reference"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryEurBankAccountId`	string (UUID)	Registered EUR bank account ID to receive SEPA transfer
`sepaReference`	string (optional)	Reference code for the SEPA transfer

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: SEPA transfer is sent automatically to the bank account.

tip

For EUR output transactions, you benefit from standard market rates and fees when converting from crypto to EUR.

COP to Crypto

warning

These deposits buy USDC and nothing else. The deposit instrument on these rails outlives our pricing window — a Colombian deposit link is valid for 7 days, a Mexican one for about a day — so honouring a converted price when the money finally lands would be exposure we do not take. Any outputCurrency other than USDC is refused with HTTP 400.

To end up in another token, convert the USDC afterwards: that is a second operation, priced when you ask for it.

COP deposits support two rails — choose the one that matches how your end-user wants to pay:

Rail	`inputPaymentMethod`	Identifier
PSE	`BANK-TRANSFER`	`depositUrl` (one-time link)
Bre-B	`BRE-B`	`breBKey` (static key)

The flow is otherwise identical from an API consumer perspective: same quote endpoint, same ticket endpoint, same webhooks.

warning

Minimum COP payin: the amount that remains after fees must be greater than 10,000 COP. Quotes that net out below that are rejected with:

{ "error": "COP payin amount after fees must be greater than 10000 COP. Please increase the amount." }

warning

Bre-B cap: Bre-B transactions are limited to 3,000 USDC on either leg — payin or payout. Anything larger is rejected with Bre-B transactions are limited to 3000 USDC (HTTP 400). Use the PSE rail (BANK-TRANSFER) for larger amounts.

COP → USDC (PSE)

Input: COP via Bank Transfer (PSE) Output: Tokens on blockchain

info

COP deposits are processed via PSE (the Colombian online banking system). After creating the ticket, the user receives a depositUrl — a payment link that must be opened in a browser to complete the bank transfer.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`COP`	Colombian Peso
`inputPaymentMethod`	`BANK-TRANSFER`	Bank transfer method (PSE)
`inputAmount`	`50000`	Amount in COP
`outputCurrency`	`USDC`	Token currency (USDC, BRLA, USDT, or EURC)
`outputPaymentMethod`	`INTERNAL`	Blockchain (internal network)
`blockchainSendMethod`	`PERMIT`	Transaction type (PERMIT or TRANSFER)

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryWalletId`	string (UUID)	Avenia wallet ID that will receive the tokens on the INTERNAL chain

Ticket Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "depositUrl": "https://checkout.example.com/...",
  "expiration": "2026-05-01T13:26:12.307Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`depositUrl`	string	PSE payment link — user must open this URL in a browser to complete payment
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be paid. COP PSE tickets expire 24 hours after creation.

Result: User opens depositUrl and completes PSE payment. After payment confirmation, tokens are credited to the specified wallet.

warning

The depositUrl is a one-time payment link valid for 24 hours. If the user abandons the payment, the ticket will expire. No funds are moved and no tokens are minted until the PSE payment is completed.

info

Sandbox testing: payment is simulated — no real PSE deposit is required and the ticket auto-completes. See Sandbox Usecases > Simulate COP Deposit for details.

COP → USDC (Bre-B)

Input: COP via Bre-B Output: Tokens on blockchain

info

Avenia returns a static Bre-B key in the ticket response. The user sends the exact inputAmount to that key from any Bre-B-enabled Colombian bank app to complete the deposit.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`COP`	Colombian Peso
`inputPaymentMethod`	`BRE-B`	Bre-B rail
`inputAmount`	`50000`	Amount in COP
`outputCurrency`	`USDC`	Token currency (USDC, BRLA, USDT, or EURC)
`outputPaymentMethod`	`INTERNAL`	Blockchain (internal network)
`blockchainSendMethod`	`PERMIT`	Transaction type (PERMIT or TRANSFER)

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryWalletId`	string (UUID)	Avenia wallet ID that will receive the tokens on the INTERNAL chain

Ticket Response

{
  "id": "bb3a6430-55c5-4c43-9d17-9262cb71e935",
  "breBKey": "@CBW0ZWQT6",
  "expiration": "2026-05-06T14:08:11.197319Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`breBKey`	string	Static Bre-B key — the user transfers the exact `inputAmount` to this key from any Bre-B-enabled Colombian bank app to complete the deposit.
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be paid. Bre-B tickets expire 24 hours after creation.

Result: User opens their banking app, selects Bre-B, sends the exact inputAmount to breBKey. After the inbound transfer is confirmed, tokens are credited to the specified wallet.

warning

The user must transfer the exact amount quoted (inputAmount) within 24 hours. Mismatched amounts or late transfers won't settle the ticket.

info

Sandbox testing: payment is simulated — no real Bre-B transfer is required and the ticket auto-completes. The same simulation pipeline used for PSE applies here. See Sandbox Usecases > Simulate COP Deposit.

Crypto to COP

COP payouts also support two rails — the choice is driven by the outputPaymentMethod in the quote AND by what the registered beneficiary supports:

Rail	`outputPaymentMethod`	Beneficiary requirement
PSE	`BANK-TRANSFER`	Beneficiary registered with full bank fields (account number, document, address, etc.)
Bre-B	`BRE-B`	Beneficiary registered with a `breBKey` OR the `breBKey` passed inline in the ticket request

warning

Bre-B cap: Bre-B transactions are limited to 3,000 USDC on either leg. A larger payout is rejected with Bre-B transactions are limited to 3000 USDC (HTTP 400). Route larger amounts through PSE (BANK-TRANSFER).

A single beneficiary can be registered with only Bre-B, only bank fields, or both — see Beneficiary Bank Accounts > Bank Guide COP. For Bre-B you can also skip the cadastro entirely and pass the breBKey directly in the ticket payload (see "Bre-B inline" below). At ticket creation, Avenia validates that the chosen rail is satisfied and rejects the ticket otherwise.

USDC → COP (PSE)

Input: USDC from blockchain Output: COP via Bank Transfer (PSE)

info

You must register a COP beneficiary bank account first with bank fields populated. See Beneficiary Bank Accounts > Bank Guide COP to set up a Colombian bank account. Use the returned beneficiaryCopBankAccountId in the ticket request.

warning

USDC only: COP payouts currently only support USDC as the input currency. Other cryptocurrencies (BRLA, USDT, EURC, etc.) are not accepted for COP withdrawals. If you hold a different token, convert it to USDC first before initiating a COP payout.

info

Minimum COP payout: 5 USDC. Quotes below this amount are rejected.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	Must be USDC — only supported input for COP payouts
`inputPaymentMethod`	`INTERNAL`	Blockchain you are sending from
`inputAmount`	`5`	Amount in USDC (minimum 5)
`outputCurrency`	`COP`	Colombian Peso
`outputPaymentMethod`	`BANK-TRANSFER`	Bank transfer method (PSE)
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketCopOutput": {
    "beneficiaryCopBankAccountId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryCopBankAccountId`	string (UUID)	Registered COP bank account ID to receive funds. Must have bank fields registered for PSE.

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762",
  "expiration": "2026-05-01T13:26:12.307Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier — use this to track the payout status
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be processed.

Result: USDC is burned from your wallet and COP is transferred to the beneficiary's Colombian bank account.

Common Errors

Error	Cause	Fix
`beneficiary does not have bank account details registered`	The beneficiary referenced by `beneficiaryCopBankAccountId` was registered as Bre-B-only.	Either register a new beneficiary with bank fields, or update the quote to use `outputPaymentMethod=BRE-B`.

USDC → COP (Bre-B)

Input: USDC from blockchain Output: COP via Bre-B

info

You must register a COP beneficiary with the recipient's Bre-B key. See Beneficiary Bank Accounts > Bank Guide COP. The Bre-B key is validated at registration time, so an invalid key fails the cadastro — not the ticket.

warning

USDC only: COP payouts only accept USDC as input. Convert other tokens to USDC first.

info

Minimum COP payout: 5 USDC.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	Must be USDC
`inputPaymentMethod`	`INTERNAL`	Blockchain you are sending from
`inputAmount`	`5`	Amount in USDC (minimum 5)
`outputCurrency`	`COP`	Colombian Peso
`outputPaymentMethod`	`BRE-B`	Bre-B rail
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketCopOutput": {
    "beneficiaryCopBankAccountId": "ee93dbbb-15a7-401b-88db-0ff12abe5a86"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryCopBankAccountId`	string (UUID)	Registered COP beneficiary ID. Must have a `breBKey` registered for Bre-B.

Ticket Response

{
  "id": "63f87aad-8994-4584-94ee-b5d182fa7acf",
  "expiration": "2026-05-01T13:26:12.307Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be processed.

Result: USDC is burned from your wallet and COP is delivered to the beneficiary's Bre-B key.

Common Errors

Error	Cause	Fix
`beneficiary does not have a Bre-B key registered`	The beneficiary referenced by `beneficiaryCopBankAccountId` does not have a `breBKey` set.	Register a new beneficiary with `breBKey`, or pass the key inline (see Bre-B inline below), or update the quote to use `outputPaymentMethod=BANK-TRANSFER`.

USDC → COP (Bre-B inline, no beneficiary)

Input: USDC from blockchain Output: COP via Bre-B

info

Skip the beneficiary cadastro entirely and pass the recipient's Bre-B key directly in the ticket payload. The key is validated against the Bre-B network at ticket creation time, so an invalid key fails the ticket up front. Only valid when the quote's outputPaymentMethod is BRE-B.

warning

USDC only: COP payouts only accept USDC as input. Convert other tokens to USDC first.

info

Minimum COP payout: 5 USDC.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	Must be USDC
`inputPaymentMethod`	`INTERNAL`	Blockchain you are sending from
`inputAmount`	`5`	Amount in USDC (minimum 5)
`outputCurrency`	`COP`	Colombian Peso
`outputPaymentMethod`	`BRE-B`	Bre-B rail
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketCopOutput": {
    "breBKey": "@CBW0ZWQT6"
  }
}

Request Parameters

Parameter	Type	Description
`breBKey`	string	Recipient's Bre-B key. Validated against the Bre-B network — invalid keys reject the ticket.

warning

Pass exactly one of beneficiaryCopBankAccountId or breBKey in ticketCopOutput — sending both is rejected.

Ticket Response

{
  "id": "63f87aad-8994-4584-94ee-b5d182fa7acf",
  "expiration": "2026-05-01T13:26:12.307Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be processed.

Result: USDC is burned from your wallet and COP is delivered to the supplied Bre-B key.

Common Errors

Error	Cause	Fix
`ticketCopOutput.breBKey is invalid`	Bre-B key not recognised by the network (not registered, not active).	Verify the key with the recipient or use a registered beneficiary.
`ticketCopOutput is invalid`	Both `beneficiaryCopBankAccountId` and `breBKey` were sent.	Pick one.

ARS to Crypto

warning

To end up in another token, convert the USDC afterwards: that is a second operation, priced when you ask for it.

Argentina uses a single rail — a local bank transfer to a destination CVU that Avenia returns at ticket creation. The end-user sends the exact inputAmount in ARS from any Argentine bank/wallet app to that CVU to complete the deposit.

ARS → USDC

Input: ARS via Bank Transfer Output: Tokens on blockchain

info

After creating the ticket, the response includes a destination cvu and bankName. The user transfers the exact inputAmount to that CVU from their Argentine bank app to complete the deposit.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`ARS`	Argentine Peso
`inputPaymentMethod`	`BANK-TRANSFER`	Local bank transfer (CVU/CBU)
`inputAmount`	`12000`	Amount in ARS
`outputCurrency`	`USDC`	Token currency (USDC, BRLA, USDT, or EURC)
`outputPaymentMethod`	`INTERNAL`	Blockchain (internal network)
`blockchainSendMethod`	`PERMIT`	Transaction type (PERMIT or TRANSFER)

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketArsInput": {
    "senderAccountNumber": "0000003100010000000001"
  },
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  }
}

Request Parameters

Parameter	Type	Description
`ticketArsInput.senderAccountNumber`	string	The end-user's own 22-digit CVU/CBU the funds are sent from
`beneficiaryWalletId`	string (UUID)	Avenia wallet ID that will receive the tokens on the INTERNAL chain

Ticket Response

{
  "id": "9355e9b9-9637-4dba-8ce5-09c6ce3b92c2",
  "cvu": "0000003100010000000001",
  "bankName": "Banco ...",
  "expiration": "2026-06-22T16:30:10.888Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`cvu`	string	Destination CVU — the user transfers the exact `inputAmount` here from their Argentine bank app
`bankName`	string	Name of the bank holding the destination CVU
`expiration`	string (ISO 8601)	Timestamp after which the ticket can no longer be paid

Result: User transfers the exact inputAmount in ARS to cvu. After the inbound transfer is confirmed, tokens are credited to the specified wallet.

warning

The user must transfer the exact amount quoted (inputAmount). Mismatched or late transfers won't settle the ticket.

info

Sandbox testing: the deposit is simulated — no real ARS transfer is required and the ticket auto-completes. See Sandbox Usecases > Simulate ARS Deposit for details.

Crypto to ARS

USDC → ARS

Input: USDC from blockchain Output: ARS via Bank Transfer (CVU/CBU)

info

You must register an ARS beneficiary bank account first via POST /v2/account/beneficiaries/bank-accounts/ars/ (CVU or CBU + recipient compliance fields). See Beneficiary Bank Accounts > Bank Guide ARS. Use the returned beneficiaryArsBankAccountId in the ticket request.

warning

USDC only: ARS payouts currently only support USDC as the input currency. Convert other tokens to USDC first.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	Must be USDC — only supported input for ARS payouts
`inputPaymentMethod`	`INTERNAL`	Blockchain you are sending from
`inputAmount`	`5`	Amount in USDC (minimum 5)
`outputCurrency`	`ARS`	Argentine Peso
`outputPaymentMethod`	`BANK-TRANSFER`	Local bank transfer (CVU/CBU)
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketArsOutput": {
    "beneficiaryArsBankAccountId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryArsBankAccountId`	string (UUID)	Registered ARS bank account ID (CVU/CBU) to receive the funds

Ticket Response

{
  "id": "0a9d7c4d-6b59-4537-8812-4b13485f5c9a"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier

Result: Avenia sends the USDC on-chain, converts it, and pays out ARS to the beneficiary's CVU/CBU. The ticket transitions UNPAID → PROCESSING → PAID.

info

Sandbox testing: the payout is simulated — no real ARS is sent and the ticket auto-completes. See Sandbox Usecases > Simulate ARS Deposit (payouts section).

MXN to Crypto

warning

To end up in another token, convert the USDC afterwards: that is a second operation, priced when you ask for it.

Mexico uses a single rail — a local bank transfer to a destination CLABE that Avenia returns at ticket creation. The end-user sends the exact inputAmount in MXN from any Mexican bank or wallet app to that CLABE to complete the deposit.

warning

The API payment method is BANK-TRANSFER. SPEI is the name of the underlying Mexican interbank network — it is not a valid API value. Sending inputPaymentMethod=SPEI or outputPaymentMethod=SPEI returns HTTP 400.

warning

MXN KYC is required. Creating any MXN ticket before the MXN rail is unlocked returns HTTP 403:

{
  "error": "Internal user does not have the required role for this route",
  "extraInfo": "MXN KYC must be approved before creating MXN tickets"
}

See KYC — MXN.

info

Monthly limit: level-1 accounts are capped at 400,000 MXN per direction per month (payin and payout are counted separately).

MXN → USDC

Input: MXN via Bank Transfer Output: Tokens on blockchain

info

After creating the ticket, the response includes a destination clabe, bankName and accountHolder. The user transfers the exact inputAmount to that CLABE from their Mexican bank app to complete the deposit.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`MXN`	Mexican Peso
`inputPaymentMethod`	`BANK-TRANSFER`	Local bank transfer (CLABE)
`inputAmount`	`1000`	Amount in MXN
`outputCurrency`	`USDC`	Token currency (USDC, BRLA, USDT, or EURC)
`outputPaymentMethod`	`INTERNAL`	Blockchain (internal network)
`blockchainSendMethod`	`PERMIT`	Transaction type (PERMIT or TRANSFER)

Ticket Request

MXN payins carry no rail-specific input block — unlike ARS, there is no sender account to declare. Send only the quote token and the blockchain output.

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryWalletId`	string (UUID)	Avenia wallet ID that will receive the tokens on the INTERNAL chain

Ticket Response

{
  "id": "3f21c5b8-2f19-4a0a-9a1c-8e0d5c2b7a41",
  "clabe": "012180001234567899",
  "bankName": "NVIO",
  "accountHolder": "Avenia LLC",
  "expiresAt": "2026-08-12T16:30:10.888Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier
`clabe`	string	Destination 18-digit CLABE — the user transfers the exact `inputAmount` here from their Mexican bank app
`bankName`	string	Name of the bank holding the destination CLABE
`accountHolder`	string	Name the destination CLABE is registered under — show it to the user so they can confirm the payee in their banking app
`expiresAt`	string (ISO 8601)	Timestamp after which the ticket can no longer be paid

Result: User transfers the exact inputAmount in MXN to clabe. After the inbound transfer is confirmed, tokens are credited to the specified wallet.

warning

The user must transfer the exact amount quoted (inputAmount). Mismatched or late transfers won't settle the ticket.

warning

Do not treat the deposit window as exactly 24 hours. Avenia requests a 24-hour window for the destination CLABE, but the window actually enforced is set by the rail and can be longer than the ticket's own validity. That asymmetry matters in one direction only: a transfer that arrives after expiresAt has passed cannot be matched to the ticket, even if the CLABE still accepts it. Treat expiresAt from the ticket response as the deadline you show the user, and re-quote rather than reusing a stale CLABE.

info

Sandbox testing: the deposit is simulated — no real MXN transfer is required and the ticket auto-completes. See Sandbox Usecases > Simulate MXN Deposit for details.

Crypto to MXN

USDC → MXN

Input: USDC from blockchain Output: MXN via Bank Transfer (CLABE)

info

You must register an MXN beneficiary bank account first via POST /v2/account/beneficiaries/bank-accounts/mxn/ (CLABE + bankId + recipient compliance fields). See Beneficiary Bank Accounts > Bank Guide MXN. Use the returned beneficiaryMxnBankAccountId in the ticket request.

warning

USDC only: MXN payouts only support USDC as the input currency. Any other input currency is rejected:

{ "error": "InvalidFieldError: inputCurrency: MXN payouts only support USDC as input currency is invalid" }

Convert other tokens to USDC first.

warning

Minimum MXN payout: 5 USDC. Below that the quote is rejected with MXN payout minimum is 5 USDC (HTTP 400).

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`USDC`	Must be USDC — only supported input for MXN payouts
`inputPaymentMethod`	`INTERNAL`	Blockchain you are sending from
`inputAmount`	`100`	Amount in USDC (minimum 5)
`outputCurrency`	`MXN`	Mexican Peso
`outputPaymentMethod`	`BANK-TRANSFER`	Local bank transfer (CLABE)
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketMxnOutput": {
    "beneficiaryMxnBankAccountId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request Parameters

Parameter	Type	Description
`beneficiaryMxnBankAccountId`	string (UUID)	Registered MXN bank account ID (CLABE) to receive the funds

Ticket Response

{
  "id": "0a9d7c4d-6b59-4537-8812-4b13485f5c9a"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier

Result: Avenia sends the USDC on-chain, converts it, and pays out MXN to the beneficiary's CLABE. The ticket transitions UNPAID → PROCESSING → PAID.

Common Errors

Error	HTTP	Cause	Fix
`InvalidFieldError: inputCurrency: MXN payouts only support USDC as input currency is invalid`	400	`inputCurrency` was not `USDC`.	Convert to USDC first, then quote.
`MXN payout minimum is 5 USDC`	400	`inputAmount` below the floor.	Quote at least 5 USDC.
`Internal user does not have the required role for this route`	403	MXN KYC not approved.	Complete MXN KYC.

info

Sandbox testing: the payout is simulated — no real MXN is sent and the ticket auto-completes. See Sandbox Usecases > Simulate MXN Deposit (payouts section).

SWIFT (International Payout)

BRL/USDC/USDT/BRLA/EURC → USD/GBP/EUR/HKD/SGD/CHF/AUD/CAD/NZD/JPY/CNY/THB/PHP/INR/KRW/IDR

Input: Your account balance (USDC, USDT, BRLA, EURC) or a PIX deposit in BRL Output: Fiat via the international SWIFT network

SWIFT lets you pay out to a foreign bank account in any supported currency. The flow is identical across every corridor — only the outputCurrency changes. The receiving side is a single SWIFT beneficiary (BIC + account number/IBAN); register it first, then reference its id.

info

Register the destination account first via POST /v2/account/beneficiaries/bank-accounts/swift/. See Beneficiary Bank Accounts > Bank Guide SWIFT. Use the returned id as beneficiarySwiftBankAccountId in the ticket request.

info

How you pay for it is up to you. A SWIFT payout can be funded from your token balance (USDC, USDT, BRLA, EURC with inputPaymentMethod=INTERNAL) or by a PIX deposit in BRL (inputPaymentMethod=PIX). Whatever you send is converted before the payout leaves — the beneficiary always receives the outputCurrency.

When you fund with PIX, the ticket is created first and returns a PIX code to pay. The payout only starts once that payment lands.

warning

COP, ARS and MXN cannot fund a SWIFT payout. Those deposits can take hours to settle — a Colombian deposit link is valid for 7 days — and a SWIFT payout is priced when the ticket is created, so honouring that price a day later is exposure we do not take. A quote from any of them to a SWIFT corridor is refused with HTTP 400.

Convert to USDC first, then pay the SWIFT payout from the balance. That is two operations, each priced when you ask for it.

warning

Company accounts only: SWIFT off-ramp requires a company account with SWIFT onboarding already completed. Individual accounts are refused. If your account is not enabled yet, talk to your account manager — there is no self-service onboarding for this rail.

Supported Currencies & Limits

These are the minimum and maximum amounts accepted per currency, expressed in the receiving (output) currency — the amount that lands in the beneficiary's account. Fees are charged on top and shown in the quote's appliedFees.

Currency	Min	Max
USD	30	10,000,000
GBP	30	1,000,000
EUR	30	1,000,000
HKD	200	10,000,000
SGD	40	1,500,000
CHF	40	1,500,000
AUD	40	1,500,000
CAD	40	1,500,000
NZD	50	1,500,000
JPY	3,000	150,000,000
CNY	200	10,000,000
THB	1,000	25,000,000
PHP	2,000	50,000,000
INR	3,000	75,000,000
KRW	40,000	1,000,000,000
IDR	400,000	15,000,000,000

Availability Windows

Most corridors can be quoted at any time. Five of them settle through a market that is only open part of the day, and can only be quoted during that window:

Currency	Window	Days
THB, PHP, IDR	01:00 – 08:30 UTC	Monday to Friday
INR, KRW	01:00 – 04:30 UTC	Monday to Friday

Outside the window, and at weekends, both the quote and the ticket request are refused with HTTP 503 and a message naming the currency and the moment the corridor reopens:

{
  "error": "SWIFT payouts in THB are unavailable right now; the corridor reopens at 2026-08-17T01:00:00Z"
}

The reopening timestamp is RFC 3339 in UTC, the same format as every other timestamp in the API. Treat a 503 on these corridors as temporary: the same request succeeds once the window opens, with no change to its parameters.

tip

A 503 can also mean the corridor's exchange rate is momentarily unavailable, in which case the message carries no reopening time. Both cases are transient and safe to retry; neither means the request was wrong.

warning

A quote is valid for 15 seconds. If you quote in the final seconds of a window and create the ticket after it closes, the ticket is refused with the same 503 even though the quote succeeded. Near the close, quote and create the ticket back to back, or wait for the next window.

Step 1 — Upload the invoice

Every SWIFT payout requires an invoice. Without it the ticket is refused, so do this before anything else. Uploading is two separate HTTP calls — the first one does not carry the file.

1a. Ask for an upload slot

POST /v2/account/documents
Content-Type: application/json

{
  "documentType": "INVOICE",
  "isDoubleSided": false
}

documentType must be exactly INVOICE. Any other value is accepted here but the ticket will reject it later. isDoubleSided is false — an invoice has one side.

The response gives you an id and a temporary upload link:

{
  "id": "9f8b2c31-4d5e-4a7b-8c9d-0e1f2a3b4c5d",
  "uploadURLFront": "https://s3.eu-west-1.amazonaws.com/...&X-Amz-Signature=..."
}

Keep the id. That is the uploadedDocumentId you will use in Step 3.

1b. Send the file to that link

PUT https://s3.eu-west-1.amazonaws.com/...&X-Amz-Signature=...
Content-Type: application/pdf

<the raw bytes of the PDF>

Send the file itself as the request body — not JSON, not multipart/form-data, and without your API credentials: the link is already signed and adding an Authorization header makes it fail. A 200 means the file is stored.

warning

The document is not usable the instant the PUT returns. It is processed first, and only then becomes Ready. Creating the ticket too early is refused with:

{ "error": "invoice document not ready" }

Poll GET /v2/account/documents/{id} until ready is true, then continue. It normally takes a few seconds. This is the single most common mistake in this flow.

Checklist before moving on


PDF only	other formats are rejected
`documentType`	must be `INVOICE`
`id` saved	you need it in Step 3
`ready: true`	confirmed via `GET /v2/account/documents/{id}`

Step 2 — Quote

Parameter	Value	Description
`inputCurrency`	`USDC`	What you are paying with — see the funding note above (`USDC`, `USDT`, `BRLA`, `EURC` or `BRL`)
`inputPaymentMethod`	`INTERNAL`	`INTERNAL` when paying from your balance, `PIX` when paying in BRL
`inputAmount`	`100`	Amount in the input currency
`outputCurrency`	`GBP`	Any supported SWIFT currency from the table above
`outputPaymentMethod`	`SWIFT`	International SWIFT payout
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

info

You may quote by outputAmount instead of inputAmount to fix the exact amount that lands in the beneficiary's account — subject to the per-currency minimum above.

Step 3 — Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketSwiftOutput": {
    "beneficiarySwiftBankAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "uploadedDocumentId": "9f8b2c31-4d5e-4a7b-8c9d-0e1f2a3b4c5d"
  }
}

The uploadedDocumentId is the id from Step 1a — the one whose file you uploaded in Step 1b and confirmed ready.

Request Parameters

Parameter	Type	Description
`beneficiarySwiftBankAccountId`	string (UUID)	Registered SWIFT beneficiary ID to receive the payout
`uploadedDocumentId`	string (UUID)	Required. ID of a supporting document (e.g. invoice) uploaded via `POST /v2/account/documents`. SWIFT payouts require a document for compliance.

info

uploadedDocumentId comes from Step 1. A document that was never uploaded, is not INVOICE, or is not yet ready makes the ticket fail — the quote is wasted and you have to quote again.

SWIFT beneficiary inline (no registration)

If you would rather not register the beneficiary first, send its fields directly in the ticket instead of beneficiarySwiftBankAccountId. Same rules, same validation — the only difference is that nothing is stored for reuse, so a second payout to the same account means sending everything again.

{
  "quoteToken": "eyJ...",
  "ticketSwiftOutput": {
    "beneficiaryName": "ACME TRADING LTD",
    "beneficiaryType": "company",
    "accountStandard": "iban",
    "accountValue": "GB33BUKB20201555555555",
    "bic": "BUKBGB22",
    "bankName": "Barclays Bank UK PLC",
    "bankCountry": "GB",
    "beneficiaryStreet": "1 Churchill Place",
    "beneficiaryCity": "London",
    "beneficiaryState": "",
    "beneficiaryPostalCode": "E14 5HP",
    "beneficiaryCountry": "GB",
    "uploadedDocumentId": "9f8b2c31-4d5e-4a7b-8c9d-0e1f2a3b4c5d"
  }
}

Parameter	Type	Description
`beneficiaryName`	string	Legal name of the account holder
`beneficiaryType`	string	`company` or `individual`
`accountStandard`	string	`iban` or `account_number`. Defaults to `account_number`
`accountValue`	string	The IBAN or the account number, matching `accountStandard`
`bic`	string	BIC/SWIFT code of the beneficiary's bank, 8 or 11 characters
`bankName`	string	Name of the beneficiary's bank
`bankCountry`	string	Country of the bank, ISO 3166-1 alpha-2 (`GB`, not `UK`)
`beneficiaryStreet`	string	Street of the beneficiary's address
`beneficiaryCity`	string	City
`beneficiaryState`	string	State or province. Send `""` where it does not apply
`beneficiaryPostalCode`	string	Postal code
`beneficiaryCountry`	string	Country of the beneficiary, ISO 3166-1 alpha-2
`intermediaryBic`	string	Optional. BIC of the correspondent bank, when the beneficiary's bank cannot be reached directly. Omit it if there is none — a wrong BIC routes the payment through a bank with no relationship to the destination
`bankOtherIdentifier`	string	Optional. Extra identifier the receiving bank requires beyond its BIC, such as a sort code or routing number

warning

Country fields take the two-letter ISO code, and only a real one. UK is a common mistake — the code for the United Kingdom is GB. USA, United States and invented codes like XX are refused.

The beneficiary's currency is the quote's outputCurrency. When you use a registered beneficiary instead, its currency must match the quote — a beneficiary registered for EUR cannot receive a GBP payout.

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Ticket identifier — use this to track the payout status

Result: USDC is burned from your wallet, converted, and paid out over SWIFT to the beneficiary's bank account. The ticket transitions UNPAID → PROCESSING → PAID. Once settled, the SWIFT network's unique end-to-end reference (UETR) is available on the ticket — the SWIFT equivalent of a PIX EndToEndId.

Blockchain Input Operations

Crypto Deposit (PERMIT Method)

Input: Tokens from wallet via blockchain Output: Tokens credited to Avenia account

info

If the wallet you specify is an Avenia Wallet, you do not need to include the PERMIT or TRANSFER fields.

Option 1: Using PERMIT Signature

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainInput": {
    "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "permit": {
      "r": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "s": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "v": 1,
      "nonce": 1,
      "deadline": 1234567890
    }
  }
}

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Option 2: Using Personal Signature

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainInput": {
    "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "personal": {
      "signature": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "deadline": 1234567890
    }
  }
}

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Crypto Deposit (TRANSFER Method)

Input: Tokens transferred manually to Avenia wallet Output: Tokens credited to Avenia account

Ticket Request

{
  "quoteToken": "eyJ...",
  "externalId": "your-reference-id"
}

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: You must manually send tokens to your Avenia wallet. After confirmation, tokens are credited to your account.

Blockchain Output Operations

Crypto Withdrawal

Input: Tokens from Avenia account Output: Tokens sent to external wallet

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "walletChain": "CELO",
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletMemo": "optional memo"
  }
}

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Result: Tokens are sent automatically to the specified wallet address.

Cross-chain Swaps

Crypto ↔ Crypto (Different Blockchains)

Input: Tokens on one blockchain Output: Tokens on another blockchain

info

You can register frequently used wallets in Beneficiary Wallets to avoid entering wallet details every time. Simply use the beneficiaryWalletId instead of providing wallet details directly.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency you are paying with
`inputPaymentMethod`	`INTERNAL`	The blockchain you are sending from
`inputAmount`	`100`	The amount you want to convert
`outputCurrency`	`USDT`	The currency you want to receive
`outputPaymentMethod`	`CELO`	The blockchain where you want to receive tokens
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type

Ticket Request - PERMIT (Recommended)

{
  "quoteToken": "eyJ...",
  "ticketBlockchainInput": {
    "walletAddress": "0x...",
    "permit": {
      "r": "0x...", "s": "0x...", "v": 1,
      "nonce": 1, "deadline": 1234567890
    }
  },
  "ticketBlockchainOutput": {
    "walletChain": "CELO",
    "walletAddress": "0x..."
  }
}

Ticket Response - PERMIT

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Ticket Request - TRANSFER (Alternative)

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "walletChain": "CELO",
    "walletAddress": "0x..."
  }
}

Ticket Response - TRANSFER

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

PERMIT: Avenia automatically pulls tokens after your signature TRANSFER: You must manually send tokens to Avenia wallet

info

Send Method is only applied to quotes where the input is blockchain

Refund Deposit Operations

REFUND DEPOSIT

Input: BRLA tokens from internal balance Output: BRL via PIX (return to original depositor)

The REFUND DEPOSIT allows you to return a deposit that the user made but for some reason no longer wants the funds. This operation uses the ticket generated from the original deposit.

info

This functionality is available only for BRL via PIX deposits that were converted to BRLA INTERNAL. To perform the refund, you must use the Ticket ID of the original deposit.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA`	The currency being refunded
`inputPaymentMethod`	`INTERNAL`	The internal payment method
`outputCurrency`	`BRL`	The currency that will be received back
`outputPaymentMethod`	`REFUND`	The refund payment method
`inputThirdParty`	`false`	Indicates that funds come from internal balance
`outputThirdParty`	`false`	Indicates that refund goes to original depositor
`blockchainSendMethod`	`PERMIT`	Defines the blockchain transaction type
`ticketRefundId`	`uuid`	Required - Original deposit ticket ID (BRL PIX → BRLA INTERNAL)

Ticket Request

info

The structure ticketBrlPixOutput passing the pixMessage is optional!

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  },
  "ticketBrlPixOutput": {
    "pixMessage": "optional PIX message"
  }
}

warning

The beneficiaryWalletId with value 00000000-0000-0000-0000-000000000000 (zeroed UUID) indicates that funds will be debited from whoever executed the operation. If a sub-account operated, funds will come out of the sub-account balance. If there is no sub-account field, funds will come out of the main account balance.

Ticket Response

{
  "id": "65feb710-029f-4469-87a4-295f0d7a3855"
}

Result: The system automatically processes the refund via PIX to the original depositor, reversing the deposit operation.

info

ticketRefundId is the ID of the original deposit ticket that needs to be refunded. You can find this ID by querying the BRL PIX → BRLA INTERNAL deposit transaction.

Avenia Internal Account Transactions

Internal Currency Transfer (BRLA/USDC/USDT/EURC → Same Currency)

Input: Tokens from internal balance (any currency with INTERNAL payment method) Output: Same currency tokens to another Avenia account (main or sub-account)

Internal transfers allow you to move tokens between Avenia accounts for any currency that supports the INTERNAL payment method (BRLA, USDC, USDT, EURC). This works for transfers from main account to sub-account, sub-account to main account, and between sub-accounts. The operation follows the same process regardless of the account types involved or the currency used.

warning

If the subAccountId={uuid} query parameter is included in the request, the operation will be executed on behalf of the specified sub-account. If omitted, the operation will be executed on behalf of the main account.

Quote Parameters

Parameter	Value	Description
`inputCurrency`	`BRLA` / `USDC` / `USDT` / `EURC`	The currency you are paying with (must support INTERNAL payment method)
`inputPaymentMethod`	`INTERNAL`	The internal payment method
`inputAmount`	`100`	The amount you want to transfer
`outputCurrency`	Same as `inputCurrency`	The currency you want to receive (must match input currency)
`outputPaymentMethod`	`INTERNAL`	The internal payment method for receiving funds

Base URL: https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate

Ticket Request

{
  "quoteToken": "eyJ...",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "28b5ccec-0286-47af-ac16-12395b40f066"
  }
}

Request Parameters

Parameter	Type	Description
`quoteToken`	string	Token obtained from the quote response
`beneficiaryWalletId`	string (UUID)	Required - The account ID of the recipient. This must be the account ID of the destination account, whether it's another sub-account ID or the main account ID

Base URL: https://api.sandbox.avenia.io:10952/v2/account/tickets/

warning

If you included the subAccountId query parameter in the quote request, you must include the same subAccountId parameter in the ticket request as well.

Ticket Response

{
  "id": "55ea4ebf-60fb-4c47-8a97-00f7659f4762"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique identifier for the ticket

Result: Tokens are transferred automatically between the specified Avenia accounts in the same currency.

Supported Assets Table

Permitted Currencies and Payment Methods

Currency	Valid Payment Methods
BRL	PIX, REFUND
USD	WIRE, ACH
EUR	SEPA
COP	BANK-TRANSFER, BRE-B
ARS	BANK-TRANSFER
MXN	BANK-TRANSFER
USD / GBP / EUR / HKD / SGD / CHF / AUD / CAD / NZD / JPY / CNY / THB / PHP / INR / KRW / IDR	SWIFT
BRLA	INTERNAL, BASE, CELO, ETHEREUM, GNOSIS, MOONBEAM, POLYGON
USDC	INTERNAL, BASE, CELO, ETHEREUM, GNOSIS, MOONBEAM, POLYGON
USDCe	POLYGON
USDT	INTERNAL, CELO, ETHEREUM, MOONBEAM, POLYGON, TRON
EURC	INTERNAL

Valid Blockchain Send Methods

Currency	Blockchain	Valid Send Methods
BRLA	POLYGON	PERMIT, TRANSFER
BRLA	MOONBEAM	PERMIT, TRANSFER
BRLA	CELO	PERMIT, TRANSFER
BRLA	GNOSIS	PERMIT, TRANSFER
BRLA	BASE	PERMIT, TRANSFER
BRLA	ETHEREUM	PERMIT, TRANSFER
USDC	POLYGON	PERMIT, TRANSFER
USDCe	POLYGON	PERMIT, TRANSFER
USDT	POLYGON	PERMIT, TRANSFER
USDC	MOONBEAM	TRANSFER
USDC	CELO	PERMIT, TRANSFER
USDC	BASE	PERMIT, TRANSFER
USDC	ETHEREUM	PERMIT, TRANSFER
USDT	ETHEREUM	TRANSFER
USDT	TRON	TRANSFER

Valid Markup Currencies

Currency	Can be used for Markup?
BRLA	Yes
USDC	Yes
USDT	Yes
EURC	No

Practical Usage

1. Choose Your Combination

Consult the table above and identify the desired conversion.

2. Adjust Parameters

Amount: Use inputAmount to define how much to convert
Direction: Swap inputCurrency and outputCurrency to reverse
Network: Change inputPaymentMethod/outputPaymentMethod to switch blockchain
Method: Select PERMIT or TRANSFER for blockchain operations

3. Consider Fees

Conversion: Fee applied when changing currencies
Network: Fee from the destination blockchain
Markup: Additional fee (if applicable)
Gas: Blockchain transaction fee

4. Execute in Sequence

Create quote first (valid for 15 seconds)
Create ticket immediately after (uses the quoteToken)
Monitor via webhooks or API

Understanding Quote Response

pairName

Field	Type	Description
pairName	string	Represents the currency pair used in the quote. Example: `"BRLAUSDT"` for a BRLA to USDT conversion.

basePrice

Field	Type	Description
basePrice	decimal	The raw exchange rate before any fees are applied. Example: `"1.002"` means 1 BRLA is worth 1.002 USDT.

appliedFees

A list of fees that were applied to the transaction. Each item in the list contains:

Field	Type	Description
type	string	The fee category. Example: `"Markup Fee"`, `"Gas Fee"`, `"In Fee"`...
description	string	A brief explanation of what the fee represents.
amount	decimal	The amount charged for this specific fee.
currency	string	The currency in which the fee is charged.

Conclusion

By now, you should have a solid understanding of how the quote system works and how to interact with the API efficiently.

We covered:

The structure of a quote, including input, output, markup, and blockchain-specific parameters.
How to make requests to the quote endpoint, whether it's PIX to Token, Token to PIX, or Blockchain to Blockchain.
How to interpret the response, including fees, exchange rates, and key transaction details.
Common validation rules and error handling, ensuring smooth and predictable API usage.
How to retrieve all tickets, allowing you to fetch your transaction history and track status changes.

With this knowledge, you're ready to integrate Avenia's quoting system into your own workflows, allowing you to seamlessly handle token conversions, fiat transactions, and blockchain swaps.

Now that you've mastered quotes, it's time to start creating tickets and executing transactions!

How It Works​

Elements of a Combination​

Modifying for Different Results​

PIX to Crypto​

BRL → BRLA/USDC/USDT/EURC​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Response Fields​

Crypto to PIX​

BRLA/USDC/USDT/EURC → BRL​

Option 1: Using Registered Beneficiary Account​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Option 2: Using PIX Key​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Option 3: Using Full Bank Account Details​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Option 4: Using brCode​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

USD to Crypto​

USD → USDC/USDT​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Response Fields​

USD Payment Methods Characteristics​

Payment Method Differences​

Currency Conversion Rules​

Crypto to USD​

USDC/USDT → USD​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

USD Output Operations​

Crypto → USD (WIRE Transfer)​

Ticket Request​

Request Parameters​

Ticket Response​

Crypto → USD (ACH Transfer)​

Ticket Request​

Request Parameters​

Ticket Response​

EUR Output Operations​

Crypto → EUR (SEPA Transfer)​

Ticket Request​

Request Parameters​

Ticket Response​

EUR to Crypto​

EUR → EURC​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

Response Fields​

EUR Payment Methods Characteristics​

Currency Conversion Rules​

Crypto to EUR​

EURC → EUR​

Quote Parameters​

Ticket Request​

Request Parameters​

Ticket Response​

COP to Crypto​

COP → USDC (PSE)​

Quote Parameters​

How It Works

Elements of a Combination

Modifying for Different Results

PIX to Crypto

BRL → BRLA/USDC/USDT/EURC

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Response Fields

Crypto to PIX

BRLA/USDC/USDT/EURC → BRL

Option 1: Using Registered Beneficiary Account

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Option 2: Using PIX Key

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Option 3: Using Full Bank Account Details

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Option 4: Using brCode

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

USD to Crypto

USD → USDC/USDT

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Response Fields

USD Payment Methods Characteristics

Payment Method Differences

Currency Conversion Rules

Crypto to USD

USDC/USDT → USD

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

USD Output Operations

Crypto → USD (WIRE Transfer)

Ticket Request

Request Parameters

Ticket Response

Crypto → USD (ACH Transfer)

Ticket Request

Request Parameters

Ticket Response

EUR Output Operations

Crypto → EUR (SEPA Transfer)

Ticket Request

Request Parameters

Ticket Response

EUR to Crypto

EUR → EURC

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

Response Fields

EUR Payment Methods Characteristics

Currency Conversion Rules

Crypto to EUR

EURC → EUR

Quote Parameters

Ticket Request

Request Parameters

Ticket Response

COP to Crypto

COP → USDC (PSE)

Quote Parameters