Wallets
Introduction
Beneficiary Wallets are wallets that are outside the Avenia API ecosystem. You can register any external wallet here for future operations on your business account or sub-account, if applicable.
Wallet Qualification
The Brazilian Central Bank requires Avenia to know who each beneficiary wallet belongs to, who holds its keys and in which country: the wallet's qualification. Avenia reports it with every on-chain payout to the wallet, and its country decides whether the payout is international:
- a wallet whose
counterpartyCountryisBRreceives domestic payouts: their quote takes no purpose code; - any other wallet, including one with no country declared yet, receives international payouts: their quote takes an
outputPurposeCode(see Purpose Code on the Quote).
See International Transfers (ACAM) for the whole flow. Wallets that send you deposits are qualified separately, as deposit sender wallets.
Through November 14, 2026 you may register a wallet with no qualification, or an incomplete one: it is PENDING.
From November 15, 2026:
- a complete qualification is required to register a beneficiary wallet or to qualify one: an incomplete one returns
400 Bad Requestnaming the first missing field; - an on-chain payout only goes to a
QUALIFIEDwallet, in Brazil too: a payout to aPENDINGwallet is refused with400 Bad Request; - a payout to a wallet not in Brazil needs an
outputPurposeCodeon its quote.
Wallets you registered before keep their status: list the ones still PENDING with GET /v2/account/beneficiaries/wallets/?qualificationStatus=PENDING and qualify them before that date.
| Field | Type | Description |
|---|---|---|
| isSelfCustody | bool | Whether the counterparty holds the wallet's private keys. Needed to qualify. |
| custodianName | string | The institution that holds the keys, such as an exchange (e.g. Example Exchange). Needed to qualify when isSelfCustody is false; not accepted when it is true. Up to 100 characters. |
| counterpartyName | string | The person or company that owns the wallet: whoever receives the payout. Needed to qualify. Up to 100 characters. |
| counterpartyCountry | string | Where the wallet is held. When isSelfCustody is false, the custodian's country, whoever owns the wallet (e.g. PY for an exchange in Paraguay, BR for an exchange in Brazil holding it for a foreign customer). When isSelfCustody is true, the counterparty's country: an individual's country of residence or a company's country of incorporation. ISO 3166-1 alpha-2 code from Countries. Needed to qualify. |
| isSameEconomicGroup | bool | Only when counterpartyCountry is not BR: whether the counterparty is a company of your economic group. Needed to qualify a wallet abroad for a company account; always false for an individual account (omit it). |
Which fields a complete qualification needs:
isSelfCustody | counterpartyCountry | Also needed |
|---|---|---|
true | BR | counterpartyName |
true | Any other country | counterpartyName, isSameEconomicGroup (company account) |
false | BR | counterpartyName, custodianName |
false | Any other country | counterpartyName, custodianName, isSameEconomicGroup (company account) |
The wallet is QUALIFIED only when its qualification is complete and valid. Through November 14, 2026, a missing field does not fail the request: the wallet is PENDING and keeps the valid fields you sent. From November 15, 2026, an incomplete qualification is refused with 400 Bad Request naming the first missing field. Nothing is assumed: no field gets a default value, the country included. A field sent with an invalid value returns 400 Bad Request naming it, and nothing is stored. See the rules.
Qualification status
Every wallet returns a qualificationStatus and an acamGroup:
| qualificationStatus | Meaning |
|---|---|
QUALIFIED | The qualification is complete and valid. |
PENDING | No qualification, or an incomplete one. Complete it with Qualify a Beneficiary Wallet. |
acamGroup is I for a wallet qualified abroad, III for a self-custody wallet qualified in Brazil, and null otherwise (a PENDING wallet included).
Create Beneficiary Wallet
Registering a new beneficiary wallet is straightforward. Let’s look at the fields:
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| alias | string | Yes | A custom name for the wallet to help identify it. |
| description | string | No | A brief description of the wallet. |
| walletAddress | string | Yes | The blockchain wallet address. |
| walletChain | string | Yes | The blockchain network of the wallet (e.g., POLYGON, ETHEREUM, BASE, TRON). A wallet can only receive the tokens supported on its network: see Supported Networks and Tokens. |
| walletMemo | string | No | Memo for the wallet. |
The body also takes the wallet's qualification: isSelfCustody, custodianName, counterpartyName, counterpartyCountry and isSameEconomicGroup. It is optional through November 14, 2026 and required from November 15, 2026.
The response returns only the wallet id; read its qualificationStatus with Get Beneficiary Wallet by ID. The purpose code is not part of a wallet: state it on each quote.
To perform this operation for a sub-account, pass the subAccountId field as a parameter to this endpoint.
On an account that requires multi-signature approval, creating a wallet (CREATE_BENEFICIARY_WALLET) returns 202 Accepted with {"operationId": "...", "status": "PENDING"}: the wallet is created only once the operation is approved.
Endpoint
Request body
{
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memooo",
"isSelfCustody": true,
"counterpartyName": "John Doe",
"counterpartyCountry": "BR"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memooo",
"isSelfCustody": true,
"counterpartyName": "John Doe",
"counterpartyCountry": "BR"
}'
Response
{
"id": "76971925-a1ca-423f-badf-0b3f2b03c51c"
}
Get all Beneficiary Wallets
Retrieve a list of all registered beneficiary wallets using filters and pagination.
Endpoint
URL Parameters
| Field | Type | Description |
|---|---|---|
| alias | string | Filters results to include only those with the specified alias. |
| walletAddress | string | Filters results to include only those with the specified wallet address. |
| walletChain | string | Filters results to include only those on a specific blockchain chain. |
| qualificationStatus | string | QUALIFIED or PENDING. PENDING lists the wallets to qualify. |
| createdAfter | int64 | Unix epoch timestamp in milliseconds (UTC) — e.g. 1700000000000. Returns results created on or after this instant (createdAt >= createdAfter). |
| createdBefore | int64 | Unix epoch timestamp in milliseconds (UTC) — e.g. 1800000000000. Returns results created strictly before this instant (createdAt < createdBefore). |
| cursor | string | Cursor for pagination. Pass the value from the previous response to retrieve the next set of results. |
To fetch wallets for a specific subAccount, pass the subAccountId field as an endpoint parameter. If you don’t pass it, it will fetch from your Main Account.
GET /v2/account/beneficiaries/wallets/?qualificationStatus=PENDING lists the Main Account wallets that still need qualification; add subAccountId to check a sub-account.
createdAfter / createdBefore are Unix epoch timestamps in milliseconds, UTC (13 digits for current dates, e.g. 1700000000000) — not seconds. If you have a value in seconds, multiply it by 1000. The lower bound is inclusive and the upper bound is exclusive, and the returned createdAt is an RFC3339 UTC string ending in Z. Convert local date boundaries to UTC before computing the epoch.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/?alias=ExampleAlias&walletAddress=0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&walletChain=POLYGON&createdAfter=1700000000000&createdBefore=1800000000000&cursor=NEXT_CURSOR" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"wallets": [
{
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memo",
"isSelfCustody": true,
"custodianName": "",
"counterpartyName": "John Doe",
"counterpartyCountry": "BR",
"isSameEconomicGroup": null,
"qualificationStatus": "QUALIFIED",
"acamGroup": "III",
"createdAt": "2025-02-20T14:13:02.065846Z"
}
],
"cursor": "MjAtMTc0MDA2MDc4MjA2NQ..."
}
Get Beneficiary Wallet by ID
Retrieve the details of a specific beneficiary wallet:
Endpoint
Request example
curl -X GET \
"https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/{YOUR_UUID_ID}" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"wallet": {
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memo",
"isSelfCustody": true,
"custodianName": "",
"counterpartyName": "John Doe",
"counterpartyCountry": "BR",
"isSameEconomicGroup": null,
"qualificationStatus": "QUALIFIED",
"acamGroup": "III",
"createdAt": "2025-02-20T14:13:02.065846Z"
}
}
Qualify a Beneficiary Wallet
Declares, completes or corrects the qualification of a wallet. It takes the same fields and rules. The qualification is replaced whole by what you send, so send the full qualification every time: a field you leave out is cleared. The wallet is QUALIFIED when it is complete. An incomplete one leaves it PENDING through November 14, 2026, and is refused from November 15, 2026. Only the qualification fields are accepted: any other field, such as alias, walletAddress, walletChain, walletMemo or purposeCode, returns 400 Bad Request ("only the qualification fields are accepted").
Endpoint
Request example
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/00000000-0000-0000-0000-000000000000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"isSelfCustody": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "Example Holdings LLC",
"counterpartyCountry": "US",
"isSameEconomicGroup": false
}'
The response is 200 OK with the updated wallet, as {"wallet": {...}}.
To qualify a sub-account's wallet, pass the subAccountId field as a query parameter. It requires the Beneficiary or Admin permission; otherwise it returns 403 Forbidden.
On an account that requires multi-signature approval, the request returns 202 Accepted with {"operationId": "...", "status": "PENDING"}: the qualification is applied automatically, on behalf of the requester, once the approvals of the operation (QUALIFY_BENEFICIARY_WALLET) reach the quorum. See Automatic execution.
Countries
Public endpoint (no authentication) listing the ISO 3166-1 alpha-2 country codes the API accepts as counterpartyCountry.
Endpoint
Response
{
"countries": [
{ "code": "AD", "name": "Andorra" },
{ "code": "AE", "name": "United Arab Emirates" },
{ "code": "BR", "name": "Brazil" }
]
}
Delete Beneficiary Wallet
Delete a specific beneficiary wallet:
Endpoint
Request example
curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Your wallet has been permanently removed from the system.