Skip to main content

About Login

Account Info​

Account Information displays all data associated with your account, including your Avenia deposit wallets, which are automatically created when you set up your Business Account. See Deposit Addresses for how to fund your account with stablecoins.

fluxogram relation between access and accounts

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/account-info

Parameters​

FieldTypeDescription
subAccountIdstringThe ID of your sub-account. Instead of fetching data from your main account, it retrieves data from this sub-account.
tip

Remember that you can only pass a subAccountId if you have already created a subAccount.

note

When you create a business account, the Bank Account - BRL is automatically initialized, providing a PIX key (linked to your entire Business Account) and a unique BR Code for each account and subaccount.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/account-info" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"id": "00000000-0000-0000-0000-000000000000",
"accountInfo": {
"id": "11111111-1111-1111-1111-111111111111",
"accountType": "INDIVIDUAL",
"name": "xxxxx",
"countrySubdivisionTaxResidence": "BR-SP",
"countryTaxResidence": "BRA",
"identityStatus": "CONFIRMED",
"fullName": "xxxxx",
"birthdate": "9999-99-30T00:00:00Z",
"taxId": "99999999999"
},
"wallets": [
{
"id": "be85cef0-d70a-47cc-9847-9014570efed5",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chain": "EVM"
},
{
"id": "3f1c2a7e-5b8d-4e6f-9a0b-1c2d3e4f5a6b",
"walletAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chain": "TRON"
}
],
"pixKey": "11111111-1111-1111-1111-111111111111",
"brCode": "00020126580014br.gov.bcb.pix013600000000-0000-0000-0000-0000000000005204000053039865802BR5915Avenia API Ltda6009SAO PAULO62070503***6304XXXX",
"clabe": "999999000000123455",
"cvu": "0009999099000000000897",
"bre-b": "@SBX000000000893",
"swiftReceivingAccount": {
"beneficiaryName": "Jane Doe",
"bankName": "Sandbox Bank",
"bic": "SBXXUS33XXX",
"accountNumber": "9999000123456789",
"routingNumber": "999999999",
"bankAddress": {
"street1": "1 Sandbox Plaza",
"street2": "",
"city": "New York",
"region": "NY",
"postalCode": "10001",
"country": "US"
}
},
"createdAt": "2025-02-18T17:00:39.854943Z"
}

clabe, cvu and bre-b are the account's fixed deposit details for MXN, ARS and COP. Each field is present only for a currency the account has unlocked; a currency that is not unlocked is left out of the response, not sent as empty or null. They are available in sandbox. See Static Deposits.

swiftReceivingAccount is the account's fixed SWIFT receiving account for USD: the bank details a sender needs to send it a SWIFT transfer. It is present only once Avenia enables SWIFT deposits for the account. See Static Deposits.

Deposit Addresses​

The wallets array returns your account's deposit addresses: one EVM address and one TRON address.

A plain on-chain transfer of a supported token to one of these addresses is credited automatically to your INTERNAL balance. You don't need to create a ticket first: Avenia creates one for the deposit automatically. The asset is kept as sent — USDC is credited as USDC, USDT as USDT.

TokenSupported networks (production)
USDCPolygon, Base, Ethereum, BNB Chain, Gnosis, Arc
USDTPolygon, Ethereum, BNB Chain, TRON
warning

Stellar is not supported. Funds sent on Stellar to these addresses are not credited. Only send the tokens and networks listed above.

  • Credit timing: the deposit is credited after network confirmations. The funds are available to spend immediately once credited.
  • Matching an open ticket: if you have an UNPAID ticket using the TRANSFER method with the same chain, token and exact amount, the deposit settles that ticket instead of creating a new one.
  • Sender wallet qualification: the sending wallet is recorded as a deposit sender wallet. Wallet qualification does not hold your funds: the deposit is credited whether or not the wallet is qualified.
  • Sandbox uses testnets instead of the production networks above.
  • Operations with a ticket (quotes with a blockchain inputPaymentMethod or outputPaymentMethod) support more networks than plain deposits. See Supported Networks and Tokens.

Account Balance​

Here, we’ll retrieve all current balances for your main account or subaccount.

info

Keep in mind that the operation is still being performed by the subaccount, so it’s also necessary to include the subAccountId parameter here.

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/balances

Example Json Response​

JSON
{
"balances": {
"BRLA": "518",
"EURC": "0",
"USDC": "1.753243",
"USDM": "0",
"USDT": "0"
}
}

Account Metadata​

The Account Metadata endpoint provides configuration flags and currency unlock status for your account or subaccount.

info

This endpoint returns various account configuration settings, including which currencies are unlocked for operations.

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/metadata

Parameters​

FieldTypeRequiredDescription
subAccountIdstringNoThe ID of your sub-account. Instead of fetching data from your main account, it retrieves data from this sub-account.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/metadata" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"skipLiveness": false,
"easierLevel1": false,
"brlUnlocked": true,
"usdUnlocked": false,
"eurUnlocked": false,
"arsUnlocked": false,
"copUnlocked": false,
"mxnUnlocked": false,
"swiftUsdUnlocked": false
}

Response Fields Explained​

FieldTypeDescription
skipLivenessbooleanWhether liveness check is skipped during KYC
easierLevel1booleanWhether easier Level 1 KYC requirements are applied
brlUnlockedbooleanWhether BRL currency operations are unlocked
usdUnlockedbooleanWhether USD currency operations are unlocked
eurUnlockedbooleanWhether EUR currency operations are unlocked
arsUnlockedbooleanWhether ARS currency operations are unlocked
copUnlockedbooleanWhether COP currency operations are unlocked
mxnUnlockedbooleanWhether MXN currency operations are unlocked
swiftUsdUnlockedbooleanWhether USD operations over the SWIFT rail are unlocked
tip

Use this endpoint to check which currencies are available for your account before attempting operations.

Access​

An Access is linked to account credentials, functioning as a login that grants access tokens. It allows management of both the Business Account and SubAccounts, depending on the assigned permissions.

A Business Account can have up to 100 accesses (admin included). Only the admin access, and accesses granted manageAccesses, can create and edit accesses.

warning

YOU NEED TO HAVE MFA OTP ENABLED TO CREATE AND EDIT ACCESSES

tip

For the complete API reference (full permission set and defaults, delegated access management, multi-signature approval, subaccount blacklist) see Accesses Management. The sections below are a quick overview of the most common flows.

Access Creation

explanation fluxogram about accesses

The creation process consists of two steps:

  1. The Access Admin (or an access with manageAccesses) initiates the creation by providing the email and OTP of the new access. A validation request is then sent to the specified email.
  2. With the email token, the new access completes the process by setting up a password.

Access Creation (STEP 1)​

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/
FieldTypeDescription
otpstringOne-time password required for creation.
emailstringEmail of the new access being created.
permissionsobjectPermission flags. Any flag left out takes its default — see the Permissions Reference.
permissions.payOutbooleanPermission for pay-outs (also gates on-chain transfers). Defaults to false.

Request body​

JSON
{
"otp": "999999",
"email": "your.new.access.email@provider.com",
"permissions": {
"payOut": true
}
}

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/accesses/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"otp": "999999",
"email": "your.new.access.email@provider.com",
"permissions": {
"payOut": true
}
}'

A token will be sent to the provided email to complete the process.

Validation of Access Creation (STEP 2)​

Endpoint​

POSThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/validate/{token}
FieldTypeDescription
passwordstringNew password for the access.
confirmPasswordstringMust match the password field.

Request body​

JSON
{
"password": "UseAStrongPassword123!",
"confirmPassword": "UseAStrongPassword123!"
}

Request example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/accesses/validate/eyJhdXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{"password": "UseAStrongPassword123!", "confirmPassword": "UseAStrongPassword123!"}'

Once validated (201 Created), the new access is ready.

Update Access Permissions​

Endpoint​

PATCHhttps://api.sandbox.avenia.io:10952/v2/auth/accesses/
warning

On PATCH, an omitted payOut, viewOnly, markup, beneficiary, enforceAllowedBeneficiaries, operationRequester or operationApprover is set to false; other omitted fields keep their stored value. Send the full set you want the access to keep — see Update Access Permissions.

Request body​

JSON
{
"id": "00000000-0000-0000-0000-000000000000",
"otp": "999999",
"permissions": {
"payOut": true,
"viewOnly": false,
"markup": true,
"beneficiary": true,
"enforceAllowedBeneficiaries": false,
"operationRequester": false,
"operationApprover": false
}
}

Request example​

cURL
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/auth/accesses/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{ ... }'

View Accesses​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/
ParameterTypeDescription
emailstringFilters accesses by specified email (exact match).
payOutbooleanFilters based on pay-out permission.

Filters on viewOnly, convert, payIn, onChain and creation date are listed in List Accesses.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses?email=your.new.access.email@provider.com&payOut=true" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"accesses": [
{
"id": "00000000-0000-0000-0000-000000000000",
"email": "your.new.access.email@provider.com",
"createdAt": "2025-02-07T19:54:17.727744Z",
"updatedAt": "2025-02-07T19:54:17.727744Z",
"frozenUntil": "0001-01-01T00:00:00Z",
"accessPermission": {
"id": "00000000-0000-0000-0000-000000000000",
"admin": true,
"payIn": true,
"payOut": true,
"convert": true,
"onChain": true,
"viewOnly": false,
"manageAssets": true,
"manageAccesses": true,
"...": "...",
"updatedAt": "2025-02-07T19:54:17.727744Z"
},
"multisigNotifications": true,
"mfa": {
"id": "00000000-0000-0000-0000-000000000000",
"createdAt": "2025-02-18T00:36:47.329722Z",
"updatedAt": "2025-02-18T00:36:47.329722Z"
}
},
...
]
}

View a Specific Access​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{ACCESS_UUID_HERE}
FieldTypeDescription
idstringThe ID of an existing access.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"access": {
"id": "00000000-0000-0000-0000-000000000000",
"email": "your.new.access.email@provider.com",
"createdAt": "2025-02-07T19:54:17.727744Z",
"updatedAt": "2025-02-07T19:54:17.727744Z",
"frozenUntil": "0001-01-01T00:00:00Z",
"accessPermission": {
"id": "00000000-0000-0000-0000-000000000000",
"admin": true,
"payOut": true,
"...": "...",
"updatedAt": "2025-02-07T19:54:17.727744Z"
},
"multisigNotifications": true,
"mfa": {
"id": "00000000-0000-0000-0000-000000000000",
"createdAt": "2025-02-18T00:36:47.329722Z",
"updatedAt": "2025-02-18T00:36:47.329722Z"
}
}
}

Delete an Access​

Endpoint​

DELETEhttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{ACCESS_UUID_HERE}?otp=999999
FieldTypeDescription
idstringThe ID of an existing access.
otpstringOne-time password (OTP) required to confirm delete.

Request example​

cURL
curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000?otp=999999" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

And that's it. After the OK, that access has been deleted. Only the admin access can delete accesses, and the admin access itself cannot be deleted.

Viewing Current Access Information​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/access-info

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/access-info" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Account Limits

This guide explains how to retrieve the operational limits for your account or subaccount. Limits are defined monthly and are crucial for understanding your account's transaction capacity.

info

To view the limits of a subaccount, simply include the subAccountId as a parameter in the request.

Get Account Limits​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/limits

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/limits" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"limitInfo": {
"blocked": false,
"createdAt": "2025-07-22T03:24:29.032379Z",
"limits": [
{
"currency": "*",
"maxFiatIn": "100000",
"maxFiatOut": "100000",
"maxChainIn": "100000",
"maxChainOut": "100000",
"usedLimit": {
"year": 2025,
"month": 7,
"usedFiatIn": "0",
"usedFiatOut": "0",
"usedChainIn": "0",
"usedChainOut": "0"
}
},
{
"currency": "BRL",
"maxFiatIn": "600000",
"maxFiatOut": "600000",
"maxChainIn": "600000",
"maxChainOut": "600000",
"usedLimit": { "..." }
},
{
"currency": "USD",
"maxFiatIn": "100000",
"maxFiatOut": "100000",
"maxChainIn": "100000",
"maxChainOut": "100000",
"usedLimit": { "..." }
}
]
}
}

Response Fields Explained​

The response contains a limitInfo object with the following fields:

FieldTypeDescription
blockedbooleanIf true, all operations for this account are blocked due to limit restrictions.
createdAtstringThe timestamp when the limit information was generated.
limitsarray of objectsAn array containing limit details for different currencies.

Each object inside the limits array has the following structure:

FieldTypeDescription
currencystringThe currency of the limit. A value of * represents the global limit, which is consumed by any operation in any currency, expressed in USD. Other values (e.g., BRL, USD) represent specific limits for operations conducted in that currency.
maxFiatInstringThe maximum monthly limit for fiat deposits.
maxFiatOutstringThe maximum monthly limit for fiat withdrawals.
maxChainInstringThe maximum monthly limit for on-chain deposits.
maxChainOutstringThe maximum monthly limit for on-chain withdrawals.
usedLimitobjectAn object detailing the consumed limit for the current month (year, month), broken down by operation type (usedFiatIn, usedFiatOut, etc.). The values are expressed in the specified currency.
tip

Currency-specific limits are expressed in their own value. For example, a maxFiatIn of 100000000 for the ARS currency means a limit of 100 million Argentine Pesos.

Conclusion​

You have learned how to manage Account Information and Accesses, including:

  • ✅ Retrieving Account Information
  • ✅ Checking Account Balances
  • ✅ Retrieving Account Metadata
  • ✅ Managing Accesses
  • ✅ Creating and Validating a New Access
  • ✅ Updating Access Permissions
  • ✅ Viewing Accesses
  • ✅ Deleting an Access
  • ✅ Checking Your Current Access Information
  • ✅ Get account limits

Following these steps provides a structured approach to handling authentication, authorization, and account management.