Skip to main content

Your First Operation

This walkthrough buys BRLA with a PIX payment in the sandbox and follows the ticket until it is paid. It uses the avenia() helper from Authentication; paste it above the code below.

In sandbox, a PIX deposit of up to R$1,000 is paid automatically a few seconds after the ticket is created, so you can run the whole flow without moving money.

1. Check your account​

status, account = avenia("GET", "/v2/account/account-info")
print(status, account["id"])

The top-level id is your main account ID. It is what you send as beneficiaryWalletId to move funds from a sub-account back to the main account.

2. Get a quote​

quote_params = {
    "inputCurrency": "BRL",
    "inputPaymentMethod": "PIX",
    "inputAmount": "100",
    "outputCurrency": "BRLA",
    "outputPaymentMethod": "INTERNAL",
    "inputThirdParty": "false",
    "outputThirdParty": "false",
}
status, quote = avenia("GET", "/v2/account/quote/fixed-rate", params=quote_params)
print(status, quote["outputAmount"], quote["appliedFees"])

The quote tells you exactly what you'll receive (outputAmount) and every fee that applies (appliedFees). The quoteToken in the response is valid for 15 seconds, so create the ticket right away.

3. Create the ticket​

import uuid

status, ticket = avenia("POST", "/v2/account/tickets/", body={
    "quoteToken": quote["quoteToken"],
    "externalId": f"first-operation-{uuid.uuid4()}",
    "ticketBlockchainOutput": {
        "beneficiaryWalletId": "00000000-0000-0000-0000-000000000000",
    },
})
assert status == 201, ticket
print(ticket["id"], ticket["expiration"])
  • externalId is your own reference. Use a unique one per operation so you can find the ticket again with GET /v2/account/tickets/?externalId=... if a response is lost.
  • The zeroed beneficiaryWalletId credits your own Avenia balance. See beneficiaryWalletId by operation for the other destinations.
  • The response carries the brCode your payer would pay in production, and the ticket's expiration.

4. Follow the ticket to the end​

import time

FINAL_STATUSES = {"PAID", "FAILED", "PARTIAL-FAILED", "CANCELED"}

for _ in range(60):  # about 5 minutes
    status, body = avenia("GET", f"/v2/account/tickets/{ticket['id']}")
    assert status == 200, body
    current = body["ticket"]["status"]
    print(current, body["ticket"]["failureReason"])
    if current in FINAL_STATUSES:
        break
    time.sleep(5)

In production, prefer webhooks to polling: a TICKET-COMPLETE event arrives for every final outcome except a cancellation you made yourself. Always read the ticket status in it before marking the operation as done — see Ticket States.

5. Check the balance​

status, balances = avenia("GET", "/v2/account/balances")
print(balances["balances"]["BRLA"])

Next steps​