Deposit Sender Wallets
Introduction
Deposit Sender Wallets are the wallets that sent crypto to your account. Avenia records the sending wallet of every crypto deposit (an on-chain transfer, a PERMIT pay-in or an internal transfer from another Avenia account) so that you can qualify it for the ACAM reports Avenia sends to the Brazilian Central Bank (BCB), the same way you qualify your beneficiary wallets. See International Transfers (ACAM) for why this matters.
- A wallet is recorded the first time it sends you a deposit, once per chain family (
EVM,TRONorINTERNAL). The same EVM address is a single wallet across every EVM chain. INTERNALwallets are other Avenia accounts that paid you with an internal transfer.- Transfers between wallets of your own account are not recorded.
- A deposit with a ticket is never blocked by the wallet qualification: you receive the funds whether the sending wallet is qualified or not. Starting November 15, 2026, a deposit without a ticket from a sender not known to be in Brazil is held until you qualify its sender.
- Repeated deposits from the same wallet only update its
lastDepositAt. They never change its qualification.
Through November 14, 2026, qualifying sender wallets is optional: a missing field leaves the wallet PENDING, an invalid value returns 400 Bad Request, and no deposit is held.
From November 15, 2026:
- a qualification you send must be complete: an incomplete one returns
400 Bad Requestnaming the first missing field; - deposits are still never refused, but an on-chain deposit without a ticket from a sender not known to be in Brazil is held, and not credited, until you qualify the sender in Brazil, or qualify it abroad and state the deposit's purpose code.
Qualify the senders you already have before that date: list them with GET /v2/account/deposit-sender-wallets/?qualificationStatus=PENDING.
Qualification status
| qualificationStatus | Meaning |
|---|---|
PENDING | The wallet has no qualification, or an incomplete one. Every new deposit from it sends a WALLET-QUALIFICATION-REQUIRED webhook. |
QUALIFIED | The wallet has a complete and valid qualification. |
When the sender is a wallet Avenia holds for another account (including your main account or one of your sub-accounts), its qualification is filled in automatically: not self-custodied, custodian Avenia SPSAV, country BR, and the name of the account that holds it as counterpartyName. It arrives QUALIFIED, so its deposits send no WALLET-QUALIFICATION-REQUIRED webhook, and they are domestic: they never take a purpose code. If Avenia doesn't have that account's name yet, the wallet arrives PENDING with only counterpartyName missing: complete it with Qualify Deposit Sender Wallet. External wallets arrive as PENDING.
The qualification fields (isSelfCustody, custodianName, counterpartyName, counterpartyCountry and isSameEconomicGroup) and their rules are the same as for beneficiary wallets; see Wallet Qualification. For a sender wallet, counterpartyName is whoever sent the funds. The purpose code is not part of the qualification: state it on the quote, see Purpose Code on the Quote. For deposits sent without a ticket from a wallet abroad, you can also give the wallet standing purpose codes, one for each band.
Wallet responses also carry acamGroup: I for a wallet qualified abroad, III for a self-custody wallet qualified in Brazil, and null otherwise (a PENDING wallet included). They also carry standingPurposeCodes: the wallet's standing purpose code for each band, UP_TO_50K and ABOVE_50K, both always present, an empty string where the band has none.
Get all Deposit Sender Wallets
Retrieve the wallets that sent deposits to your account, with filters and pagination.
Endpoint
URL Parameters
| Field | Type | Description |
|---|---|---|
| chainFamily | string | EVM, TRON or INTERNAL. |
| qualificationStatus | string | PENDING or QUALIFIED. Use PENDING to find the wallets you still need to qualify. |
| createdAfter | int64 | Unix epoch timestamp in milliseconds (UTC). Returns wallets first recorded on or after this instant. |
| createdBefore | int64 | Unix epoch timestamp in milliseconds (UTC). Returns wallets first recorded strictly before this instant. |
| cursor | string | Cursor for pagination. Pass the value from the previous response to retrieve the next set of results. |
To fetch the wallets of a sub-account, pass the subAccountId field as a parameter. If you don't pass it, it fetches from your Main Account.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/?qualificationStatus=PENDING" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"wallets": [
{
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chainFamily": "EVM",
"isSelfCustody": null,
"custodianName": "",
"counterpartyName": "",
"counterpartyCountry": "",
"isSameEconomicGroup": null,
"qualificationStatus": "PENDING",
"standingPurposeCodes": {
"UP_TO_50K": "",
"ABOVE_50K": ""
},
"acamGroup": null,
"lastDepositAt": "2026-10-01T19:44:27.098166Z",
"createdAt": "2026-10-01T19:38:43.176527Z"
}
],
"cursor": "NC0xNzkwODgzNTIzMTc2"
}
Qualify Deposit Sender Wallet
Declare, complete or correct the qualification of a wallet, with the fields and rules of beneficiary wallets. The whole qualification is replaced by what you send: a field you leave out is cleared. The wallet is QUALIFIED when the qualification is complete and valid. An incomplete one leaves it PENDING through November 14, 2026, and is refused with 400 Bad Request from November 15, 2026.
Only the qualification fields are accepted: any other field, such as walletAddress or purposeCode, returns 400 Bad Request.
Qualifying a wallet settles the deposits held from it, right away:
- in Brazil (
counterpartyCountryBR): its deposits are domestic and take no purpose code, so every deposit held from it is released; - abroad: the deposits held from it whose purpose code you already stated are released. The others are released as soon as you state their code.
A qualification that changes isSelfCustody, custodianName, counterpartyName, counterpartyCountry or isSameEconomicGroup also clears the wallet's standing purpose codes, since they were stated for the previous counterparty. Sending the same qualification again keeps them.
To perform this operation for a sub-account, pass the subAccountId field as a parameter. It requires the Beneficiary or Admin permission; otherwise it returns 403 Forbidden.
Endpoint
Request example
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/00000000-0000-0000-0000-000000000000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"isSelfCustody": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "John Doe",
"counterpartyCountry": "AR",
"isSameEconomicGroup": false
}'
Response
Returns the updated wallet:
{
"wallet": {
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chainFamily": "EVM",
"isSelfCustody": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "John Doe",
"counterpartyCountry": "AR",
"isSameEconomicGroup": false,
"qualificationStatus": "QUALIFIED",
"standingPurposeCodes": {
"UP_TO_50K": "",
"ABOVE_50K": ""
},
"acamGroup": "I",
"lastDepositAt": "2026-10-01T19:44:27.098166Z",
"createdAt": "2026-10-01T19:38:43.176527Z"
}
}
Set Standing Purpose Codes
Give a wallet abroad a purpose code for every deposit it sends you without a ticket, one code for each band. Use it when one wallet sends you many such deposits, all for the same reason: without it, each deposit from that wallet waits for its own code, whether it is held or credited without one.
- Only a wallet
QUALIFIEDabroad takes standing codes: qualify it first. - Each code must be in the table of its band: the
UP_TO_50Kcode from the table for operations of up to USD 50,000, theABOVE_50Kcode from the table for operations above it. The purpose code catalog lists the bands of each code; a few codes are in both tables. - A deposit held from that wallet is released right away with the code of its own band, by its value in USD, and no
DEPOSIT-PURPOSE-CODE-REQUIREDwebhook is sent. The deposit is credited with that code, so noTICKET-PURPOSE-CODE-REQUIREDfollows either. - A deposit from that wallet credited without a code takes the code of its ticket's band (
quote.purposeCodeBand) as itsquote.inputPurposeCode, and noTICKET-PURPOSE-CODE-REQUIREDwebhook is sent. - A deposit whose band has no standing code waits for its own code as usual: state it with
PATCH /v2/account/deposit-holds/{hold-id}/purpose-codewhen it is held, or withPATCH /v2/account/tickets/{ticket-id}/purpose-codewhen it is credited. - A deposit that already has its code, from its ticket's quote or stated by you, keeps it.
- Setting the codes releases at once the deposits from that wallet that wait for their code (
AWAITING_PURPOSE_CODE) and whose band now has one. It also gives the credited deposits from that wallet still missing a code the code of their band. - A hold released this way has
releaseReasonSTANDING_PURPOSE_CODE, with itspurposeCode,purposeCodeBandandusdAmount. - The codes apply only while the wallet is
QUALIFIEDabroad. Qualifying the wallet in Brazil makes its deposits domestic: they are released without a code, and the standing codes are not used. - A new qualification that changes any of its fields clears both codes, since they were stated for the previous counterparty. Set them again if they still apply.
- Each call replaces both codes. A band you leave out or send empty has no code. Send both empty to remove them: later deposits from the wallet wait for their own code again. Deposits that already got a code keep it.
To perform this operation for a sub-account, pass the subAccountId field as a parameter. It requires the Beneficiary or Admin permission; otherwise it returns 403 Forbidden.
Endpoint
Request body
| Field | Type | Description |
|---|---|---|
| purposeCodes.UP_TO_50K | string | The code for deposits worth up to USD 50,000, from that band's table. Empty or left out: no code for this band. |
| purposeCodes.ABOVE_50K | string | The code for deposits worth more than USD 50,000, from that band's table. Empty or left out: no code for this band. |
Request example
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/00000000-0000-0000-0000-000000000000/purpose-code" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"purposeCodes": {
"UP_TO_50K": "YOUR_UP_TO_50K_CODE",
"ABOVE_50K": "YOUR_ABOVE_50K_CODE"
}
}'
Response
Returns the updated wallet:
{
"wallet": {
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chainFamily": "EVM",
"isSelfCustody": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "John Doe",
"counterpartyCountry": "AR",
"isSameEconomicGroup": false,
"qualificationStatus": "QUALIFIED",
"standingPurposeCodes": {
"UP_TO_50K": "YOUR_UP_TO_50K_CODE",
"ABOVE_50K": "YOUR_ABOVE_50K_CODE"
},
"acamGroup": "I",
"lastDepositAt": "2026-10-01T19:44:27.098166Z",
"createdAt": "2026-10-01T19:38:43.176527Z"
}
}
Otherwise:
| Status | When |
|---|---|
400 Bad Request | The body has a field other than purposeCodes, a code is not in the table of its band (the error names purposeCodes.UP_TO_50K or purposeCodes.ABOVE_50K), or the wallet is not one of the account's. |
409 Conflict | A code was sent for a wallet in Brazil (counterpartyCountry BR), whose deposits are domestic and take no code, or for a wallet not QUALIFIED abroad yet. |
Get Deposits of a Deposit Sender Wallet
List the deposits a wallet sent to your account, newest first. It includes deposits made before the wallet was recorded.
Endpoint
URL Parameters
| Field | Type | Description |
|---|---|---|
| createdAfter | int64 | Unix epoch timestamp in milliseconds (UTC). Returns deposits made on or after this instant. |
| createdBefore | int64 | Unix epoch timestamp in milliseconds (UTC). Returns deposits made strictly before this instant. |
| cursor | string | Cursor for pagination. Pass the value from the previous response to retrieve the next set of results. |
To fetch the deposits of a sub-account's wallet, pass the subAccountId field as a parameter.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/00000000-0000-0000-0000-000000000000/deposits" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"deposits": [
{
"ticketId": "00000000-0000-0000-0000-000000000000",
"txHash": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chain": "POLYGON",
"asset": "BRLA",
"amount": "10",
"createdAt": "2026-10-01T19:38:35.344165Z"
}
],
"cursor": "MS0xNzkwODgyNDI1NzA1"
}
| Field | Description |
|---|---|
ticketId | The deposit's ticket. null when the deposit is an internal transfer from another Avenia account, because the ticket belongs to the sender. |
txHash | Transaction hash of the deposit. |
chain | The chain the deposit arrived on, such as POLYGON, TRON or INTERNAL. |
asset | Token received. |
amount | Amount received, as a decimal string. |
createdAt | When the deposit was made. |