Deposit Asset
Create a deposit via Lightning, USDT, USDC, USDCE, BRLA, or BRS.
POST /api/deposit/asset
New Central Bank requirement (ACAM), mandatory from November 15, 2026
A deposit that delivers crypto to an external wallet you have not declared before must carry a
walletDeclaration: who holds the wallet, in which country and, for a
holder outside Brazil, the purpose code. Deposits to Hodle wallets of your account need nothing new.
Read Wallet Declaration (ACAM).
Create a Pix charge to buy crypto. BRS defaults to the account’s own Hodle wallet; external Solana delivery requires account enablement (ask support). Other assets are delivered to the supplied address.
Request
curl --request POST \
--url https://api.hodle.com.br/api/deposit/asset \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"value": 5000,
"address": "lnbc500u1pj...",
"asset": "LIGHTNING",
"externalId": "my-order-123"
}'const res = await fetch('https://api.hodle.com.br/api/deposit/asset', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
value: 5000,
address: 'lnbc500u1pj...',
asset: 'LIGHTNING',
externalId: 'my-order-123',
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/deposit/asset",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"value": 5000,
"address": "lnbc500u1pj...",
"asset": "LIGHTNING",
"externalId": "my-order-123",
},
)
data = res.json()Delivering to an external on-chain wallet (USDT, USDC, USDCE, BRLA, BTC)? The first
deposit to a new wallet needs a walletDeclaration. See the
external wallet example and
Wallet Declaration (ACAM).
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
value | integer | Yes | Amount in BRL cents. Minimum 100 (R$1.00); BRS on Base requires at least R$5.00 after fees. |
address | string | Cond. | Destination address. Required for LIGHTNING, USDT, USDC, USDCE, and BRLA. For BRS, omit it to receive in your Hodle wallet; external Solana addresses require delivery enablement and signing credentials. BTC also requires an address. |
asset | string | Yes | Asset type: LIGHTNING, USDT, USDC, USDCE, BRLA, BRS, DEPIX, LBTC, or BTC. |
network | string | Cond. | On-chain network for the asset. Required for USDT, USDC, USDCE, and BRLA; BRS supports solana (the default when omitted) and base. Not needed for LIGHTNING. See Assets & Networks. |
externalId | string | No | Reconciliation and idempotency key. Retries return the original deposit. A UUID is generated if omitted. See Idempotency. |
subAccountId | string | No | Your subaccount for this deposit. Defaults to the main account. See What subAccountId does. |
walletPin | string | Cond. | BRS to an external address only. PIN of the wallet paying the delivery fee. |
protectedSymmetricKey | string | Cond. | BRS to an external address only. That wallet's protectedSymmetricKey. |
walletId | string | No | BRS to an external address only. Which of the account's wallets pays the delivery fee. Defaults to the default wallet (of the subAccountId when one is sent). |
maxDeliveryFeeCents | integer | No | BRS to an external address only. The highest delivery fee you accept, in BRL cents (minimum 1). The deposit is refused if the live fee exceeds it. |
expiresIn | integer | No | Seconds until the Pix code stops being payable. Default 600 (10 minutes); accepted range 60 to 86400 (24 hours). The response returns the resulting expiresAt. See QR code expiration. |
taxId | string | No | CPF/CNPJ of the payer, when the payer is not the account holder. Digits only or masked. Requires third-party operations enabled on the account. See Who can pay the PIX. |
walletDeclaration | object | Cond. | Holder of the destination wallet, required by the Central Bank (ACAM) for the first deposit to an external wallet. Not needed for Hodle wallets of your account or for a wallet already declared. See walletDeclaration. |
markup | object | No | Your own spread on top of Hodle's fee, paid to your wallet. { "bps": 0-1000, "fixedCents": >= 0 }, integers. Requires partner markup enabled on the account. See Partner markup. |
walletDeclaration
Brazilian regulation requires every international transfer of virtual assets to be reported to the Central Bank (ACAM). When the destination is an external wallet we have not seen on your account, tell us who holds it. Full rules, purpose codes and errors: Wallet Declaration (ACAM).
| Field | Type | Required | Description |
|---|---|---|---|
isSelfCustody | boolean | Yes | Must be true: the holder controls the wallet's private keys. |
counterpartyName | string | Yes | Full name or legal name of the holder, 1 to 100 characters. |
counterpartyCountry | string | Yes | ISO 3166-1 alpha-2, uppercase. BR makes the transfer domestic. |
reason | string | Yes | Why the money goes to this wallet, 3 to 500 characters. |
purposeCode | string | Cond. | Required when the holder is outside Brazil. 91992 (up to USD 50,000) or 12186 (above) for a purchase of virtual assets. |
The declaration is saved per address and network and reused on later deposits.
Deposit to an external wallet (walletDeclaration)
curl --request POST \
--url https://api.hodle.com.br/api/deposit/asset \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"value": 50000,
"asset": "USDT",
"network": "polygon",
"address": "0x4444444444444444444444444444444444444444",
"externalId": "order-3002",
"walletDeclaration": {
"isSelfCustody": true,
"counterpartyName": "Maria Silva",
"counterpartyCountry": "BR",
"reason": "Purchase of USDT for my own wallet"
}
}'const res = await fetch('https://api.hodle.com.br/api/deposit/asset', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
value: 50000,
asset: 'USDT',
network: 'polygon',
address: '0x4444444444444444444444444444444444444444',
externalId: 'order-3002',
walletDeclaration: {
isSelfCustody: true,
counterpartyName: 'Maria Silva',
counterpartyCountry: 'BR',
reason: 'Purchase of USDT for my own wallet',
},
}),
})
const data = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/deposit/asset",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"value": 50000,
"asset": "USDT",
"network": "polygon",
"address": "0x4444444444444444444444444444444444444444",
"externalId": "order-3002",
"walletDeclaration": {
"isSelfCustody": True,
"counterpartyName": "Maria Silva",
"counterpartyCountry": "BR",
"reason": "Purchase of USDT for my own wallet",
},
},
)
data = res.json()A holder outside Brazil also needs purposeCode. See the international example.
Partner markup
Add your own spread to a deposit with markup. It is charged on top of Hodle's fee, never instead of it:
markupCents = round(value × bps / 10000) + fixedCents
fee = Hodle fee + markupCentsThe payer receives the asset for value − fee. The markup is delivered to your own wallet (the API key owner's wallet on the deposit's network, never a subaccount's) in the deposit's asset, shortly after the deposit is delivered. A deposit that is refunded before delivery carries no markup.
- Send at least one of
bpsorfixedCentsabove zero;{ "bps": 0, "fixedCents": 0 }is the same as no markup. - Supported routes:
USDTonpolygon,USDConpolygonandUSDConbase, when your account settles them on its own deposit route. Any other asset, network or account route answersMARKUP_UNSUPPORTED_ROUTEbefore the deposit is created. A markup is never silently dropped. - Your account needs a wallet on the deposit's network to receive the markup (
MARKUP_PARTNER_WALLET_NOT_FOUNDotherwise). - When
feereachesvalue, the deposit is refused as below the fee.
{
"value": 10000,
"asset": "USDT",
"network": "polygon",
"address": "0xYourCustomerWallet",
"markup": { "bps": 100, "fixedCents": 50 }
}The response then carries fee (Hodle fee + markup) and feeBreakdown:
{
"fee": 340,
"feeBreakdown": { "hodleFeeCents": 190, "partnerMarkupCents": 150 }
}QR code expiration
Use expiresAt to show when the Pix code expires. After expiry, create a new deposit with a new externalId for a fresh code. Reusing an externalId returns the original expiry; expiresIn does not extend it.
When expiresAt is null, the payment route sets its own lifetime and ignores expiresIn.
What subAccountId does
Depending on your account setup, subAccountId either selects the customer's settlement account or records the customer for reconciliation while the deposit uses your account's KYC, fees and limits. Ask support which setup applies. The subaccount must belong to your platform; the same setup applies to Wallet Payout.
Who can pay the PIX
The PIX charge returned by this endpoint can only be paid by the CPF/CNPJ that owns the
account the deposit belongs to — the subaccount holder when subAccountId selects the
subaccount's own account, your own account otherwise. A PIX
sent by anyone else is refused by the bank at payment time and no crypto is delivered.
To accept a PIX paid by a third party — for example when you charge your own end customer on your account — ask support to enable third-party deposits on the account.
Assets & Networks
| Asset | Networks | Address format |
|---|---|---|
LIGHTNING | lightning | Lightning invoice or LNURL email |
USDT | polygon, arbitrum, solana, tron | EVM address (0x...); Solana address on solana; Tron address on tron |
USDC | polygon, base, gnosis, solana, stellar | EVM address (0x...); Solana address on solana; own Hodle wallet on stellar |
USDCE | gnosis | EVM address (0x...) |
BRLA | polygon, base | EVM address (0x...) |
BRS | solana, base | Own Hodle Solana wallet (any Solana address with external delivery — ask support); on base, the account's own EVM wallet |
DEPIX | spark, liquid | Spark address (spark1...) or Liquid address |
BTC | spark, bitcoin | Spark address (spark1...) or Bitcoin address; defaults to bitcoin |
LBTC | liquid | Liquid address |
Available networks per asset can depend on your account configuration and KYC level. For the full matrix across every endpoint see Assets & Networks.
Solana delivery and BRS are enabled per account (ask support). See USDC or USDT to a Solana wallet, BRS, and Stellar for route requirements.
Address Formats
For LIGHTNING assets, the address can be:
- A Lightning invoice starting with
lnbc,lntb, orlnbcrt - An LNURL email in the format
user@domain.com
Use the address format in the table above. For USDC on Stellar, send the account’s existing Hodle Stellar wallet address.
Receiving crypto without a Pix
A customer who already holds stablecoins can send the asset directly to the wallet address
from POST /api/wallet/get, without a deposit. Subscribe to
DEPOSIT_ONCHAIN_RECEIVED to be notified when it
arrives. A deposit this endpoint delivers to the account's own wallet sends that event too, next
to DEPOSIT_ASSET_SUCCESS; deduplicate by transaction hash.
For BRS, omit address to receive in the account's own Hodle Solana wallet, or send a
base58 Solana address to deliver there (external delivery must be enabled on the account — ask support). With
network: "base", omit address to receive in the account's own Hodle Base wallet, or send
one of the account's own EVM addresses. See BRS.
USDC or USDT to a Solana wallet
A Pix deposit can deliver USDC or USDT to any Solana wallet. Solana delivery must be enabled on your account (ask support).
Quote with outputPaymentMethod: "SOLANA". Delivery costs are excluded (bridgeFeeIncluded: false), so the delivered amount is below the quoted outputAmount. Send the wallet's base58 address, rather than a token account.
{
"value": 5000,
"asset": "USDC",
"network": "solana",
"address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
"externalId": "order-2041"
}Listen for these webhooks:
| Step | Event | What it means |
|---|---|---|
| Pix paid | DEPOSIT_PIX_CONFIRMED | The Pix settled. Safe to release your customer's order. |
| Delivered | DEPOSIT_ASSET_SUCCESS | The asset landed on address. valueInCurrency is the amount delivered. |
| Not delivered | DEPOSIT_ASSET_FAILED | The Pix was paid but the asset could not be delivered. The refund is confirmed later by DEPOSIT_ASSET_REFUNDED. |
The Solana transaction hash of the delivery and the exact amount received are on
GET /api/deposit/{id} once the deposit completes, so you can show it on
any Solana explorer.
BRS to an external Solana wallet
External BRS delivery to any Solana address is enabled per account (ask support). Its fee is paid separately in BRS from your Hodle Solana wallet before the Pix charge is created. Keep enough BRS in that wallet to cover it.
Preview the live fee with POST /api/quote and the destination address. Send the paying wallet’s walletPin and protectedSymmetricKey; use walletId to select it and maxDeliveryFeeCents to cap the fee.
{
"value": 10000,
"asset": "BRS",
"network": "solana",
"address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
"externalId": "order-1029",
"walletPin": "424242",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
"maxDeliveryFeeCents": 200
}{
"success": true,
"externalId": "order-1029",
"walletCharge": "66fa1c0e9b1d4a0012ab34cd",
"qrCode": "00020101021226...",
"expiresAt": "2026-09-30T13:15:00.000Z",
"fee": 0,
"fxRateAtTx": 1,
"deliveryFee": {
"feeCents": 144,
"recipientHasTokenAccount": false,
"txHash": "5KqV...",
"expiresAt": "2026-09-30T13:15:00.000Z"
}
}- The Pix charge expires after
expiresIn(10 minutes by default;expiresAtanddeliveryFee.expiresAtcarry the same moment). If it is not paid, the fee goes back to the wallet that paid it in full, about 10 minutes after expiry. - A Pix that still lands after that refund is delivered to the account's own Hodle wallet, not to the external address.
- Retrying with the same
externalIdreturns the original deposit and does not debit the fee again.
Response
{
"success": true,
"externalId": "my-order-123",
"qrCode": "00020101021226...",
"expiresAt": "2026-10-05T14:10:00.000Z",
"fee": 100,
"fxRateAtTx": 408000.50,
"walletCharge": "66fc0b7e2a4b5c6d7e8f9012"
}Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the deposit was created. |
externalId | string | Your reconciliation ID or the generated UUID. |
qrCode | string | null | QR code for the deposit. |
expiresAt | string | null | When the Pix code stops being payable (ISO 8601), from expiresIn. null when the rail sets its own lifetime. See QR code expiration. |
fee | number | Fee in BRL cents. With a partner markup, Hodle's fee plus the markup. |
feeBreakdown | object | Only with a partner markup: hodleFeeCents and partnerMarkupCents, which add up to fee. |
fxRateAtTx | number | Exchange rate at the time of the transaction. |
walletCharge | string | null | Wallet charge identifier. |
deliveryFee | object | null | BRS only: the delivery fee debited for an external address, null for the account's own wallet. See BRS to an external Solana wallet. |
Errors
| Status | When |
|---|---|
400 | Invalid fields, unsupported asset/network, missing or invalid address, or Solana delivery unavailable (DEPOSIT_FAILED). Creation failures may return DEPOSIT_UNAVAILABLE or THIRD_PARTY_NOT_ENABLED. External BRS delivery: missing credentials (DELIVERY_FEE_REQUIRED), fee above your cap (DELIVERY_FEE_ABOVE_MAX, with quotedDeliveryFeeCents), or insufficient BRS for the fee (INSUFFICIENT_BRS_FOR_DELIVERY_FEE). Missing or invalid walletDeclaration for an external wallet (DEPOSIT_FAILED). Invalid markup (MARKUP_INVALID), a markup on a route that cannot carry it (MARKUP_UNSUPPORTED_ROUTE), or no wallet of yours on the network to receive it (MARKUP_PARTNER_WALLET_NOT_FOUND). GET by id: empty id or more than 128 characters. |
401 | Missing or invalid API key, or wrong external-delivery wallet PIN (INVALID_PIN). Repeated wrong PINs lock wallet operations for 24 hours. |
403 | KYC, limits, third-party operations or the asset is not enabled. External BRS delivery disabled (BRS_EXTERNAL_DELIVERY_DISABLED). markup sent without partner markup enabled (MARKUP_NOT_ENABLED). |
404 | Deposit or subaccount not found under your API key. |
409 | externalId is already used by another account. Use a different value. |
429 | Rate limit exceeded; wait for the Retry-After duration. |
503 | External BRS delivery fee cannot be priced or debited (DELIVERY_FEE_UNAVAILABLE). Retry. Partner markup settlement temporarily unavailable (MARKUP_SETTLEMENT_UNAVAILABLE). |
{
"success": false,
"error": "Validation failed",
"details": [
{ "field": "value", "message": "Expected number, received string" }
]
}{
"success": false,
"error": "A deposit with this externalId already exists"
}Idempotency
Retries with the same externalId return your original deposit, including its walletCharge, qrCode, fee and fxRateAtTx. This also applies to simultaneous requests. Use the same key after a timeout.
You can retrieve the QR code with GET /api/deposit/{id}.
Rate limit
Requests are limited to 60 per minute per API key, counted across every API route (creating deposits included), plus 500 per minute per IP.
GET /api/deposit/{id}
Reads a deposit by its walletCharge, webhook trackId, or externalId. Use it to poll while a customer waits or reconcile a missed webhook.
Request
curl --request GET \
--url https://api.hodle.com.br/api/deposit/trk_abc123 \
--header "Authorization: Bearer $API_KEY"const res = await fetch(
'https://api.hodle.com.br/api/deposit/trk_abc123',
{ headers: { Authorization: `Bearer ${process.env.HODLE_API_KEY}` } },
)
const data = await res.json()import os, requests
res = requests.get(
"https://api.hodle.com.br/api/deposit/trk_abc123",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
)
data = res.json()Parameters
| Field | In | Required | Description |
|---|---|---|---|
id | path | Yes | The walletCharge, trackId or externalId of the deposit. |
subAccountId | query | Cond. | Required when the deposit was created with subAccountId. Send the same id back. |
Response
The same body as
GET /api/deposit/asset/{externalId} below;
see its fields and status.
Prefer the webhooks and use polling
as a fallback. When you poll, keep the whole API key under the
rate limit of 60 requests per minute: poll a deposit every 5
seconds only while your customer is watching it, back off to every 30–60
seconds otherwise, and stop at COMPLETED, REFUNDED or EXPIRED. Keep polling a failed deposit until the refund is confirmed. FIAT_PAID is the same moment as the
DEPOSIT_PIX_CONFIRMED webhook: the
PIX settled and the asset is on its way.
GET /api/deposit/asset/{externalId}
Reads a deposit back: whether the PIX was paid, whether the asset was delivered, and — on your own virtual account — who paid the QR code.
Poll it, or use it to reconcile after a
DEPOSIT_ASSET_SUCCESS webhook.
Request
curl --request GET \
--url https://api.hodle.com.br/api/deposit/asset/my-order-123 \
--header "Authorization: Bearer $API_KEY"const res = await fetch(
'https://api.hodle.com.br/api/deposit/asset/my-order-123',
{ headers: { Authorization: `Bearer ${process.env.HODLE_API_KEY}` } },
)
const data = await res.json()import os, requests
res = requests.get(
"https://api.hodle.com.br/api/deposit/asset/my-order-123",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
)
data = res.json()Parameters
| Field | In | Required | Description |
|---|---|---|---|
externalId | path | Yes | The externalId of the deposit — your own value, or the UUID we generated and returned on the POST. |
subAccountId | query | Cond. | Required when the deposit was created with subAccountId. Send the same id back. |
Response
{
"success": true,
"data": {
"externalId": "my-order-123",
"walletCharge": "68b1f0c2a4d3e50011aa22bb",
"trackId": "trk_abc123",
"status": "COMPLETED",
"processingStep": null,
"asset": "USDT",
"network": "polygon",
"address": "0x000000000000000000000000000000000000dEaD",
"value": 5000,
"valueInBrl": "50.00",
"fee": 100,
"feeInBrl": "1.00",
"fxRateAtTx": 5.55,
"receivedAmount": 8820000,
"receivedAmountDecimals": 6,
"transactionHash": "0xabc...",
"qrCode": "00020126...",
"expiresAt": "2026-08-30T12:10:00.000Z",
"endToEndId": "E1823612020260830120000000000001",
"paidAt": "2026-08-30T12:00:00.000Z",
"payer": {
"name": "FULANO DE TAL",
"taxId": "12345678901"
},
"confirmedAt": "2026-08-30T12:00:31.000Z",
"createdAt": "2026-08-30T11:59:02.000Z",
"updatedAt": "2026-08-30T12:00:31.000Z"
}
}Fields
| Field | Type | Description |
|---|---|---|
externalId | string | Your reconciliation key. |
walletCharge | string | Hodle id of the charge, the same one the POST returned. |
trackId | string | null | Hodle tracking id of the operation. |
status | string | PENDING, FIAT_PAID, PROCESSING, COMPLETED, FAILED, REFUNDED or EXPIRED. See below. |
processingStep | string | null | Where a PROCESSING deposit currently is. Report it, never route on it. |
asset | string | Asset being delivered. |
network | string | Network the asset is delivered on. |
address | string | Destination address of the delivery. |
value | integer | Amount in BRL cents. |
valueInBrl | string | Same amount, decimal string. |
fee | integer | Fee in BRL cents. |
feeInBrl | string | Same fee, decimal string. |
fxRateAtTx | number | null | Exchange rate at the time of the transaction. |
receivedAmount | integer | null | Amount actually delivered, in the asset's smallest unit. |
receivedAmountDecimals | integer | null | Decimals of receivedAmount. |
transactionHash | string | null | On-chain tx hash of the delivery, when there is one. |
qrCode | string | null | The PIX QR code / BR Code we handed you on creation. |
expiresAt | string | null | ISO-8601 time the QR code stops being payable, the same value the POST returned. null when unavailable or the payment route sets its own lifetime. |
endToEndId | string | null | End-to-end id of the PIX that funded the deposit. null until it is paid. |
paidAt | string | null | ISO-8601 time the PIX settled, as reported by the settling institution (not when we processed it). When the institution does not report it, the time Hodle received the settlement confirmation. |
payer | object | null | Who paid the PIX — see Who paid the QR code. |
confirmedAt | string | null | ISO-8601 timestamp of the delivery. |
createdAt | string | ISO-8601 creation timestamp. |
updatedAt | string | ISO-8601 timestamp of the last change. |
Status
| Status | Meaning |
|---|---|
PENDING | Charge created, PIX not paid yet. |
FIAT_PAID | Fiat payment received; the asset has not yet been delivered. paidAt and endToEndId are available. Keep polling. |
PROCESSING | Fiat payment received, asset delivery in progress. Keep polling. |
COMPLETED | Asset delivered. transactionHash is set when the delivery has one. |
FAILED | The deposit was paid but could not be delivered. Hodle returns the PIX to the payer; keep polling for the refund. Never shown before the PIX is paid. |
REFUNDED | The PIX was refunded to the payer. |
EXPIRED | The charge expired without being paid. If a PIX still arrives for it afterwards, it is honored: the deposit moves on to FIAT_PAID and is delivered normally. |
Who paid the QR code
payer carries the identity of whoever actually paid the PIX, as the payer's bank
reports it.
| Field | Type | Description |
|---|---|---|
name | string | null | Name of the payer. |
taxId | string | null | CPF/CNPJ of the payer, digits only. |
payer is null before payment, when the bank does not report the payer, or when your account has no virtual account. Ask support to enable a virtual account if you need payer identity.