Quotes and Tickets

Basic Concepts

What is a Quote

A quote is the first step for any transaction. It calculates the price, fees, and validity before execution.

Flow:

Request → Send transaction parameters
Calculation → System calculates price, fees, and validity
Response → Receive quoteToken to use in the ticket

What is a Ticket

A ticket executes the transaction using the quoteToken obtained from the quote.

Flow:

Creation → Use quoteToken + specific parameters
Execution → System processes the transaction
Monitoring → Track status until completion

Ticket Lifecycle

TICKET-CREATED → DEPOSIT-PROCESSING → DEPOSIT-SUCCESS → DELIVERY-PROCESSING → DELIVERY-SUCCESS → TICKET-COMPLETE
     ↓                    ↓                    ↓              ↓                    ↓
  DEPOSIT-FAILED    DELIVERY-FAILED     TICKET-COMPLETE   DELIVERY-FAILED     TICKET-COMPLETE

tickets fluxogram

info

For operations on behalf of a sub-account, simply add the subAccountId parameter to both the quote and ticket. The values must be identical in both calls.

API Reference - Quotes

Endpoint

GET /v2/account/quote/fixed-rate

Parameters

Required Parameters

Field	Type	Description
`inputCurrency`	string	The currency you are paying with
`inputPaymentMethod`	string	The payment method you are using
`outputCurrency`	string	The currency you want to receive
`outputPaymentMethod`	string	The method you want to receive funds
`inputAmount`	decimal.Decimal	The amount you want to pay/deposit. Required if `outputAmount` is not provided.
`outputAmount`	decimal.Decimal	The amount you want to receive. Required if `inputAmount` is not provided.
`inputThirdParty`	bool	Specifies whether the input is coming from a third party. `true` or `false`.
`outputThirdParty`	bool	Specifies whether the output is going to a third party. `true` or `false`.
`blockchainSendMethod`	string	Defines the blockchain transaction type. Can be `TRANSFER` or `PERMIT`. Required for blockchain inputs.

Optional Parameters

Field	Type	Description
`markupFloatingFee`	decimal.Decimal	A percentage fee added on top of the transaction. Example: `0.01` for 1%.
`markupInputFixedFee`	decimal.Decimal	A fixed fee applied to the input amount. Example: `10.00` in all input operations.
`markupOutputFixedFee`	decimal.Decimal	A fixed fee applied to the output amount. Example: `5.00` in all output operations.
`markupCurrency`	string	The currency in which the markup fee will be charged. Example: `BRLA`, `USDC` or `USDT`.
`subAccountId`	string	The sub-account ID to perform the operation on behalf of.

warning

Either inputAmount or outputAmount must be provided, but not both at the same time.

Example

# Regular quote
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "inputCurrency=BRL" \
--data-urlencode "inputPaymentMethod=PIX" \
--data-urlencode "inputAmount=100" \
--data-urlencode "outputCurrency=BRLA" \
--data-urlencode "outputPaymentMethod=POLYGON"

# Quote for sub-account
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "inputCurrency=BRL" \
--data-urlencode "inputPaymentMethod=PIX" \
--data-urlencode "inputAmount=100" \
--data-urlencode "outputCurrency=BRLA" \
--data-urlencode "outputPaymentMethod=POLYGON" \
--data-urlencode "subAccountId=YOUR_SUB_ACCOUNT_ID"

Response

{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "inputCurrency": "BRL",
  "inputPaymentMethod": "PIX",
  "inputAmount": "100",
  "outputCurrency": "BRLA",
  "outputPaymentMethod": "POLYGON",
  "outputAmount": "99.749583",
  "markupAmount": "0",
  "markupCurrency": "",
  "inputThirdParty": false,
  "outputThirdParty": false,
  "appliedFees": [
    {
      "type": "Markup Fee",
      "description": "Total markup fees represented in the input currency.",
      "amount": "0",
      "currency": "BRL"
    },
    {
      "type": "In Fee",
      "description": "Fees due to input currency and input payment method.",
      "amount": "0.2",
      "currency": "BRL"
    },
    {
      "type": "Conversion Fee",
      "description": "Fees due to conversion from input currency to output currency.",
      "amount": "0",
      "currency": "BRL"
    },
    {
      "type": "Out Fee",
      "description": "Fees due to output currency and output payment method.",
      "amount": "0.05",
      "currency": "BRL"
    },
    {
      "type": "Gas Fee",
      "description": "Fees due to blockchain transaction costs.",
      "amount": "0.000417",
      "currency": "BRL"
    }
  ],
  "basePrice": "1",
  "pairName": "BRLBRLA"
}

API Reference - Tickets

Endpoint

POST /v2/account/tickets/

Base Body

Field	Type	Required	Description
`quoteToken`	string	✅	The quote token received from the quote response.
`externalId`	string	❌	An identifier for internal tracking purposes in your system.

Additional Fields by Operation Type

For PIX Input

{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBrlPixInput": {
    "additionalData": "optional PIX message"
  }
}

Field	Type	Required	Description
`additionalData`	string	❌	Additional information in the PIX transaction.

For Blockchain Input (PERMIT)

{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBlockchainInput": {
    "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "permit": {
      "r": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "s": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "v": 1,
      "nonce": 1,
      "deadline": 1234567890
    }
  }
}

Field	Type	Required	Description
`walletAddress`	string	✅	The wallet address that will be sending the tokens.
`permit.r`	string	✅	The r component of the permit signature.
`permit.s`	string	✅	The s component of the permit signature.
`permit.v`	number	✅	The v component of the permit signature.
`permit.nonce`	number	✅	The nonce value for the permit signature.
`permit.deadline`	number	✅	The deadline timestamp for the permit signature.

For Blockchain Input (Personal Signature)

{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBlockchainInput": {
    "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "personal": {
      "signature": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "deadline": 1234567890
    }
  }
}

Field	Type	Required	Description
`walletAddress`	string	✅	The wallet address that will be sending the tokens.
`personal.signature`	string	✅	The personal signature for the transaction.
`personal.deadline`	number	✅	The deadline timestamp for the signature.

info

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

For Blockchain Output

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
  }
}

Field	Type	Required	Description
`beneficiaryWalletId`	string	✅	The ID of the registered beneficiary wallet that will receive the funds.

For Blockchain Output (Direct)

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBlockchainOutput": {
    "walletChain": "CELO",
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletMemo": "optional memo"
  }
}

Field	Type	Required	Description
`walletChain`	string	✅	The blockchain network of the destination wallet (e.g., `CELO`, `POLYGON`, `ETHEREUM`).
`walletAddress`	string	✅	The public address of the destination wallet.
`walletMemo`	string	❌	A memo or tag required by certain wallets or exchanges.

For PIX Output

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketBrlPixOutput": {
    "beneficiaryBrlBankAccountId": "00000000-0000-0000-0000-000000000000",
    "pixMessage": "optional PIX message"
  }
}

Field	Type	Required	Description
`beneficiaryBrlBankAccountId`	string	✅	The ID of the beneficiary account that this PIX belongs to.
`pixMessage`	string	❌	A message you want to be sent in the PIX.

For USD WIRE Output

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketUsdWireOutput": {
    "beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000"
  }
}

Field	Type	Required	Description
`beneficiaryUsdBankAccountId`	string	✅	The ID of the beneficiary account that this WIRE transfer belongs to.

For USD ACH Output

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketUsdOutput": {
    "beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000",
    "achReference": "optional ACH reference"
  }
}

Field	Type	Required	Description
`beneficiaryUsdBankAccountId`	string	✅	The ID of the beneficiary account that this ACH transfer belongs to.
`achReference`	string	❌	A reference code you want to be sent with the ACH transfer.

For EUR SEPA Output

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketEurSepaOutput": {
    "beneficiaryEurBankAccountId": "00000000-0000-0000-0000-000000000000",
    "sepaReference": "optional SEPA reference"
  }
}

Field	Type	Required	Description
`beneficiaryEurBankAccountId`	string	✅	The ID of the beneficiary account that this SEPA transfer belongs to.
`sepaReference`	string	❌	A reference you want to be sent with the SEPA transfer.

For Markup

{
  "quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id",
  "ticketMarkupInput": {
    "markupWalletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Field	Type	Required	Description
`markupWalletAddress`	string	✅	Your Avenia Wallet address to receive the markup.

warning

The markup must be sent to your Avenia Wallet, which belongs to your Business Account (BA) or sub-account if applicable. Avenia will automatically route the markup amount to this wallet.

API Reference - Tickets Management

Get All Tickets

This endpoint allows you to retrieve the entire history of created tickets.

Endpoint

GET /v2/account/tickets/

Parameters

Parameter	Type	Description
`subAccountId`	string	Filter by sub-account ID
`createdAfter`	string	Fetch tickets created after a specific date
`createdBefore`	string	Fetch tickets created before a specific date
`cursor`	string	Used for pagination
`status`	string	Filter tickets by their current status (`PENDING`, `PAID`, etc.)
`inputCurrency`	string	Filter by the input currency used in the ticket
`outputCurrency`	string	Filter by the output currency received in the ticket
`outputPaymentMethod`	string	Filter by the payment method used for the output
`endToEndId`	string	Filter by identifier assigned to each PIX transaction
`externalId`	string	Filter by the externalId, an identifier assigned to each ticket for internal tracking purposes

Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "subAccountId=YOUR_SUB_ACCOUNT_ID" \
--data-urlencode "status=PAID"

Get Ticket by ID

Retrieve a specific ticket by its unique identifier.

Endpoint

GET /v2/account/tickets/{ticket-id}

Parameters

Parameter	Type	Description
`ticket-id`	string	The unique identifier of the ticket

Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/TICKET-UUID-HERE" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Create Ticket

Create a new ticket using a quote token.

Endpoint

POST /v2/account/tickets/

Body Parameters

Field	Type	Required	Description
`quoteToken`	string	✅	The quote token received from the quote response.
`externalId`	string	❌	An identifier for internal tracking purposes in your system.

Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "externalId": "your-reference-id"
}'

Monitoring

Webhook Events

Tickets emit real-time events throughout their lifecycle:

TICKET-CREATED - The ticket has been successfully created
DEPOSIT-PROCESSING - The deposit phase has started and is currently being processed
DEPOSIT-SUCCESS - The deposit was completed successfully
DEPOSIT-FAILED - The deposit attempt has failed
DELIVERY-PROCESSING - The delivery phase (e.g., transfer of tokens or funds) is now in progress
DELIVERY-SUCCESS - The delivery was completed successfully
DELIVERY-FAILED - The delivery attempt has failed
TICKET-COMPLETE - The entire ticket lifecycle has been completed, regardless of the outcome

Markup and Fees

Markup allows you to add an extra fee on top of Avenia's standard pricing, giving you control over how much you charge your users for transactions.

For example, Avenia charges a 1% fee on swaps, which goes directly to Avenia. However, if you want to charge an additional 1% fee to your own customers, you can apply a markup. This means that both Avenia and you will collect a fee from the transaction.

warning

The markup must be sent to your Avenia Wallet, which belongs to your Business Account (BA) or sub-account if applicable. Avenia will automatically route the markup amount to this wallet.

Markup Types

1. Markup Floating Fee

Set the percentage fee you want to charge on each transaction.

Parameter	Type	Description	Example
`markupFloatingFee`	decimal.Decimal	A percentage fee added on top of the transaction	`0.01` for 1%

Example:

curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupFloatingFee=0.01"

2. Markup Input Fixed Fee

Define a fixed fee applied at the moment of payment.

Parameter	Type	Description	Example
`markupInputFixedFee`	decimal.Decimal	A fixed fee applied to the input amount	`5.00` in input currency

Example:

curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupInputFixedFee=5.00"

3. Markup Output Fixed Fee

Define a fixed fee applied when receiving funds.

Parameter	Type	Description	Example
`markupOutputFixedFee`	decimal.Decimal	A fixed fee applied to the output amount	`2.00` in output currency

Example:

curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupOutputFixedFee=2.00"

4. Markup Currency

Choose the currency in which you want to receive the markup.

Parameter	Type	Description	Valid Values
`markupCurrency`	string	The currency in which the markup fee will be charged	`BRLA`, `USDC`, `USDT`, `EURC`

Examples:

# Receive markup in BRLA
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupCurrency=BRLA"

# Receive markup in USDC
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupCurrency=USDC"

Blockchain Transaction Methods

PERMIT (Recommended)

You will sign a transaction allowing Avenia to instantly pull the tokens from your wallet, ensuring a seamless and automatic transfer. Since the transaction is executed immediately, the final amount will not change.

Advantages:

✅ Instant execution - No manual transfer required
✅ Price protection - Amount locked during quote validity
✅ Automatic processing - Avenia handles everything

When to use:

For automated operations
When you have signing capabilities
When price stability is important

TRANSFER

You will need to proactively send the tokens to your Avenia Wallet. This means Avenia will lock in the value for a certain period of time, which may result in additional costs due to price fluctuations.

Advantages:

✅ Simple implementation - No special signatures needed
✅ No approval required - Just send tokens

Disadvantages:

❌ Price fluctuation risk - Amount may change before execution
❌ Manual process - Requires user action
❌ Potential additional costs - Due to price movements

Choosing Between PERMIT and TRANSFER

Use PERMIT when:

Building automated systems
Price certainty is critical
You can handle transaction signing

Use TRANSFER when:

Simple implementation is priority
Manual process is acceptable
You cannot handle signatures

Third Party Fields

The fields inputThirdParty and outputThirdParty exist for operations involving third parties, but are currently inactive.

info

For all current operations, set both fields to false. This ensures future compatibility without affecting current functionality.

Basic Concepts​

What is a Quote​

What is a Ticket​

Ticket Lifecycle​

API Reference - Quotes​

Endpoint​

Parameters​

Required Parameters​

Optional Parameters​

Example​

Response​

API Reference - Tickets​

Endpoint​

Base Body​

Additional Fields by Operation Type​

For PIX Input​

For Blockchain Input (PERMIT)​

For Blockchain Input (Personal Signature)​

For Blockchain Output​

For Blockchain Output (Direct)​

For PIX Output​

For USD WIRE Output​

For USD ACH Output​

For EUR SEPA Output​

For Markup​

API Reference - Tickets Management​

Get All Tickets​

Endpoint​

Parameters​

Example​

Get Ticket by ID​

Endpoint​

Parameters​

Example​

Create Ticket​

Endpoint​

Body Parameters​

Example​

Monitoring​

Webhook Events​

Markup and Fees​

Markup Types​

1. Markup Floating Fee​

2. Markup Input Fixed Fee​

3. Markup Output Fixed Fee​

4. Markup Currency​

Blockchain Transaction Methods​

PERMIT (Recommended)​

TRANSFER​

Choosing Between PERMIT and TRANSFER​

Third Party Fields​

Basic Concepts

What is a Quote

What is a Ticket

Ticket Lifecycle

API Reference - Quotes

Endpoint

Parameters

Required Parameters

Optional Parameters

Example

Response

API Reference - Tickets

Endpoint

Base Body

Additional Fields by Operation Type

For PIX Input

For Blockchain Input (PERMIT)

For Blockchain Input (Personal Signature)

For Blockchain Output

For Blockchain Output (Direct)

For PIX Output

For USD WIRE Output

For USD ACH Output

For EUR SEPA Output

For Markup

API Reference - Tickets Management

Get All Tickets

Endpoint

Parameters

Example

Get Ticket by ID

Endpoint

Parameters

Example

Create Ticket

Endpoint

Body Parameters

Example

Monitoring

Webhook Events

Markup and Fees

Markup Types

1. Markup Floating Fee

2. Markup Input Fixed Fee

3. Markup Output Fixed Fee

4. Markup Currency

Blockchain Transaction Methods

PERMIT (Recommended)

TRANSFER

Choosing Between PERMIT and TRANSFER

Third Party Fields