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

FieldTypeRequiredDescription
valueintegerYesAmount in BRL cents. Minimum 100 (R$1.00); BRS on Base requires at least R$5.00 after fees.
addressstringCond.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.
assetstringYesAsset type: LIGHTNING, USDT, USDC, USDCE, BRLA, BRS, DEPIX, LBTC, or BTC.
networkstringCond.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.
externalIdstringNoReconciliation and idempotency key. Retries return the original deposit. A UUID is generated if omitted. See Idempotency.
subAccountIdstringNoYour subaccount for this deposit. Defaults to the main account. See What subAccountId does.
walletPinstringCond.BRS to an external address only. PIN of the wallet paying the delivery fee.
protectedSymmetricKeystringCond.BRS to an external address only. That wallet's protectedSymmetricKey.
walletIdstringNoBRS 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).
maxDeliveryFeeCentsintegerNoBRS 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.
expiresInintegerNoSeconds 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.
taxIdstringNoCPF/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.
walletDeclarationobjectCond.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.
markupobjectNoYour 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).

FieldTypeRequiredDescription
isSelfCustodybooleanYesMust be true: the holder controls the wallet's private keys.
counterpartyNamestringYesFull name or legal name of the holder, 1 to 100 characters.
counterpartyCountrystringYesISO 3166-1 alpha-2, uppercase. BR makes the transfer domestic.
reasonstringYesWhy the money goes to this wallet, 3 to 500 characters.
purposeCodestringCond.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 + markupCents

The 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 bps or fixedCents above zero; { "bps": 0, "fixedCents": 0 } is the same as no markup.
  • Supported routes: USDT on polygon, USDC on polygon and USDC on base, when your account settles them on its own deposit route. Any other asset, network or account route answers MARKUP_UNSUPPORTED_ROUTE before 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_FOUND otherwise).
  • When fee reaches value, 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

AssetNetworksAddress format
LIGHTNINGlightningLightning invoice or LNURL email
USDTpolygon, arbitrum, solana, tronEVM address (0x...); Solana address on solana; Tron address on tron
USDCpolygon, base, gnosis, solana, stellarEVM address (0x...); Solana address on solana; own Hodle wallet on stellar
USDCEgnosisEVM address (0x...)
BRLApolygon, baseEVM address (0x...)
BRSsolana, baseOwn Hodle Solana wallet (any Solana address with external delivery — ask support); on base, the account's own EVM wallet
DEPIXspark, liquidSpark address (spark1...) or Liquid address
BTCspark, bitcoinSpark address (spark1...) or Bitcoin address; defaults to bitcoin
LBTCliquidLiquid 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, or lnbcrt
  • 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.

POST /api/deposit/asset
{
  "value": 5000,
  "asset": "USDC",
  "network": "solana",
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "externalId": "order-2041"
}

Listen for these webhooks:

StepEventWhat it means
Pix paidDEPOSIT_PIX_CONFIRMEDThe Pix settled. Safe to release your customer's order.
DeliveredDEPOSIT_ASSET_SUCCESSThe asset landed on address. valueInCurrency is the amount delivered.
Not deliveredDEPOSIT_ASSET_FAILEDThe 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.

Request
{
  "value": 10000,
  "asset": "BRS",
  "network": "solana",
  "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "externalId": "order-1029",
  "walletPin": "424242",
  "protectedSymmetricKey": "AoofiKHyVRLvdrknnXzoIh1Gd1YTwLaOBn4ibm103a4d...",
  "maxDeliveryFeeCents": 200
}
200 OK
{
  "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; expiresAt and deliveryFee.expiresAt carry 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 externalId returns the original deposit and does not debit the fee again.

Response

200 OK
{
  "success": true,
  "externalId": "my-order-123",
  "qrCode": "00020101021226...",
  "expiresAt": "2026-10-05T14:10:00.000Z",
  "fee": 100,
  "fxRateAtTx": 408000.50,
  "walletCharge": "66fc0b7e2a4b5c6d7e8f9012"
}

Fields

FieldTypeDescription
successbooleanWhether the deposit was created.
externalIdstringYour reconciliation ID or the generated UUID.
qrCodestring | nullQR code for the deposit.
expiresAtstring | nullWhen the Pix code stops being payable (ISO 8601), from expiresIn. null when the rail sets its own lifetime. See QR code expiration.
feenumberFee in BRL cents. With a partner markup, Hodle's fee plus the markup.
feeBreakdownobjectOnly with a partner markup: hodleFeeCents and partnerMarkupCents, which add up to fee.
fxRateAtTxnumberExchange rate at the time of the transaction.
walletChargestring | nullWallet charge identifier.
deliveryFeeobject | nullBRS only: the delivery fee debited for an external address, null for the account's own wallet. See BRS to an external Solana wallet.

Errors

StatusWhen
400Invalid 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.
401Missing or invalid API key, or wrong external-delivery wallet PIN (INVALID_PIN). Repeated wrong PINs lock wallet operations for 24 hours.
403KYC, 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).
404Deposit or subaccount not found under your API key.
409externalId is already used by another account. Use a different value.
429Rate limit exceeded; wait for the Retry-After duration.
503External BRS delivery fee cannot be priced or debited (DELIVERY_FEE_UNAVAILABLE). Retry. Partner markup settlement temporarily unavailable (MARKUP_SETTLEMENT_UNAVAILABLE).
400 Bad Request
{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "value", "message": "Expected number, received string" }
  ]
}
409 Conflict
{
  "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

FieldInRequiredDescription
idpathYesThe walletCharge, trackId or externalId of the deposit.
subAccountIdqueryCond.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

FieldInRequiredDescription
externalIdpathYesThe externalId of the deposit — your own value, or the UUID we generated and returned on the POST.
subAccountIdqueryCond.Required when the deposit was created with subAccountId. Send the same id back.

Response

200 OK
{
  "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

FieldTypeDescription
externalIdstringYour reconciliation key.
walletChargestringHodle id of the charge, the same one the POST returned.
trackIdstring | nullHodle tracking id of the operation.
statusstringPENDING, FIAT_PAID, PROCESSING, COMPLETED, FAILED, REFUNDED or EXPIRED. See below.
processingStepstring | nullWhere a PROCESSING deposit currently is. Report it, never route on it.
assetstringAsset being delivered.
networkstringNetwork the asset is delivered on.
addressstringDestination address of the delivery.
valueintegerAmount in BRL cents.
valueInBrlstringSame amount, decimal string.
feeintegerFee in BRL cents.
feeInBrlstringSame fee, decimal string.
fxRateAtTxnumber | nullExchange rate at the time of the transaction.
receivedAmountinteger | nullAmount actually delivered, in the asset's smallest unit.
receivedAmountDecimalsinteger | nullDecimals of receivedAmount.
transactionHashstring | nullOn-chain tx hash of the delivery, when there is one.
qrCodestring | nullThe PIX QR code / BR Code we handed you on creation.
expiresAtstring | nullISO-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.
endToEndIdstring | nullEnd-to-end id of the PIX that funded the deposit. null until it is paid.
paidAtstring | nullISO-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.
payerobject | nullWho paid the PIX — see Who paid the QR code.
confirmedAtstring | nullISO-8601 timestamp of the delivery.
createdAtstringISO-8601 creation timestamp.
updatedAtstringISO-8601 timestamp of the last change.

Status

StatusMeaning
PENDINGCharge created, PIX not paid yet.
FIAT_PAIDFiat payment received; the asset has not yet been delivered. paidAt and endToEndId are available. Keep polling.
PROCESSINGFiat payment received, asset delivery in progress. Keep polling.
COMPLETEDAsset delivered. transactionHash is set when the delivery has one.
FAILEDThe 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.
REFUNDEDThe PIX was refunded to the payer.
EXPIREDThe 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.

FieldTypeDescription
namestring | nullName of the payer.
taxIdstring | nullCPF/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.