Skip to main content

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, TRON or INTERNAL). The same EVM address is a single wallet across every EVM chain.
  • INTERNAL wallets 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.
Optional through November 14, 2026, required from November 15, 2026

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 Request naming 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​

qualificationStatusMeaning
PENDINGThe wallet has no qualification, or an incomplete one. Every new deposit from it sends a WALLET-QUALIFICATION-REQUIRED webhook.
QUALIFIEDThe wallet has a complete and valid qualification.
Wallets held at Avenia

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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/

URL Parameters​

FieldTypeDescription
chainFamilystringEVM, TRON or INTERNAL.
qualificationStatusstringPENDING or QUALIFIED. Use PENDING to find the wallets you still need to qualify.
createdAfterint64Unix epoch timestamp in milliseconds (UTC). Returns wallets first recorded on or after this instant.
createdBeforeint64Unix epoch timestamp in milliseconds (UTC). Returns wallets first recorded strictly before this instant.
cursorstringCursor for pagination. Pass the value from the previous response to retrieve the next set of results.
info

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
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/?qualificationStatus=PENDING" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"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 (counterpartyCountry BR): 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.

info

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​

PATCHhttps://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/{YOUR_UUID_ID}

Request example​

cURL
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:

JSON
{
"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 QUALIFIED abroad takes standing codes: qualify it first.
  • Each code must be in the table of its band: the UP_TO_50K code from the table for operations of up to USD 50,000, the ABOVE_50K code 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-REQUIRED webhook is sent. The deposit is credited with that code, so no TICKET-PURPOSE-CODE-REQUIRED follows either.
  • A deposit from that wallet credited without a code takes the code of its ticket's band (quote.purposeCodeBand) as its quote.inputPurposeCode, and no TICKET-PURPOSE-CODE-REQUIRED webhook 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-code when it is held, or with PATCH /v2/account/tickets/{ticket-id}/purpose-code when 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 releaseReason STANDING_PURPOSE_CODE, with its purposeCode, purposeCodeBand and usdAmount.
  • The codes apply only while the wallet is QUALIFIED abroad. 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.
info

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​

PATCHhttps://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/{YOUR_UUID_ID}/purpose-code

Request body​

FieldTypeDescription
purposeCodes.UP_TO_50KstringThe 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_50KstringThe 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
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:

JSON
{
"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:

StatusWhen
400 Bad RequestThe 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 ConflictA 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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/deposit-sender-wallets/{YOUR_UUID_ID}/deposits

URL Parameters​

FieldTypeDescription
createdAfterint64Unix epoch timestamp in milliseconds (UTC). Returns deposits made on or after this instant.
createdBeforeint64Unix epoch timestamp in milliseconds (UTC). Returns deposits made strictly before this instant.
cursorstringCursor for pagination. Pass the value from the previous response to retrieve the next set of results.
info

To fetch the deposits of a sub-account's wallet, pass the subAccountId field as a parameter.

Request example​

cURL
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​

JSON
{
"deposits": [
{
"ticketId": "00000000-0000-0000-0000-000000000000",
"txHash": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chain": "POLYGON",
"asset": "BRLA",
"amount": "10",
"createdAt": "2026-10-01T19:38:35.344165Z"
}
],
"cursor": "MS0xNzkwODgyNDI1NzA1"
}
FieldDescription
ticketIdThe deposit's ticket. null when the deposit is an internal transfer from another Avenia account, because the ticket belongs to the sender.
txHashTransaction hash of the deposit.
chainThe chain the deposit arrived on, such as POLYGON, TRON or INTERNAL.
assetToken received.
amountAmount received, as a decimal string.
createdAtWhen the deposit was made.