Crypto Top-ups

A crypto top-up lets you add funds to your own Confirmo balance by sending crypto to a permanent top-up address. Merchants typically use this to pre-fund payouts and refunds.

Before you start

Register the accounts you'll send from. Add every wallet or exchange account you top up from to your Crypto Address Book with the TOP_UP designation, and wait until it is ACTIVE. This is how Confirmo knows the funds are yours. It replaces the Travel Rule information you'd otherwise have to give for each transfer.

Creating your top-up account

curl -X POST https://confirmo.net/api/v3/topups/crypto/accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balanceAsset": "USD",
    "notifyUrl": "https://merchant.example/hooks/topups",
    "reference": "treasury-topups"
  }'

Response 201 Created

{
  "id": "dac1a2b3c4d5e7f8",
  "status": "ENABLED",
  "balanceAsset": "USD",
  "notifyUrl": "https://merchant.example/hooks/topups",
  "reference": "treasury-topups",
  "addresses": [
    {
      "address": "0xd46faFF817D27c8C10edC580eB573cd4E8fC424d",
      "paymentMethodIds": [
        "ETHEREUM-BLOCKCHAIN-MAINNET-ETH-CURRENCY",
        "ETHEREUM-BLOCKCHAIN-MAINNET-USDC-STANDARD",
        "ETHEREUM-BLOCKCHAIN-MAINNET-USDT-STANDARD"
      ]
    },
    {
      "address": "TJ9yD14Nj9j7xAB9kf14qMjdZR43bE1Z2L",
      "paymentMethodIds": ["TRON-BLOCKCHAIN-MAINNET-USDT-STANDARD"]
    }
  ],
  "createdAt": 1772539200,
  "updatedAt": 1772539200
}

One top-up account gives you an address on every supported network. The addresses are permanent and can be reused.

What you can send. Each address lists in paymentMethodIds exactly which assets it accepts. Send only those assets, on that network.

Sending a top-up

1. Pick the address for the network you want to use, and make sure it accepts your asset.
2. Send the funds from an ACTIVE address-book entry.
3. Confirmo detects the transaction and moves it through the statuses below. Your balance is credited when the top-up reaches DONE.

The sending wallet pays the blockchain network fee.

Unregistered sources

If a top-up comes from a wallet or exchange account that isn't in your address book, or is still PENDING, Confirmo holds it without crediting it:

• Register and verify the source account. The held top-up is credited once the entry becomes ACTIVE.
• If you don't register it, contact support to have the funds returned.

Top-up statuses

Top-ups use the same statuses as deposits. The full descriptions are in the Deposit Lifecycle. Here's what each one means for a top-up:

Webhooks

If the account has a notifyUrl, Confirmo sends:

• Top-up event (crypto.topup) on every status change, with the same top-up object as GET /v3/topups/crypto.
• Account event (crypto.topup.account) when the account's status changes, for example when it is BLOCKED.

These work exactly like Deposit Webhooks, including signature validation. If no notifyUrl is set, status emails go to your account email instead.

Listing top-ups

curl "https://confirmo.net/api/v3/topups/crypto?status=DONE&createdAtFrom=1772438400&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can filter by accountId, address, chain, paymentAsset, balanceAsset, status, createdAtFrom and createdAtTo (inclusive Unix seconds), and paginate with limit (max 100) and offset.

Example item

{
  "id": "dep1a2b3c4d5e7f9",
  "accountId": "dac1a2b3c4d5e7f8",
  "address": "0xd46faFF817D27c8C10edC580eB573cd4E8fC424d",
  "chain": "ETHEREUM-BLOCKCHAIN-MAINNET",
  "paymentAsset": "USDC",
  "paymentAmount": 50000,
  "balanceAsset": "USD",
  "balanceAmount": 49985.00,
  "exchangeRate": 0.9997,
  "status": "DONE",
  "txHash": "0xc1069c068492e9fa6ea017f226a9c5949781eab340157a14556c5e1017a95070",
  "receivedAt": 1772539200,
  "reference": "treasury-topups",
  "notifyUrl": "https://merchant.example/hooks/topups"
}

exchangeRate is left out when nothing was converted.

Managing your top-up account

PATCH accepts status, balanceAsset, notifyUrl and reference. Leave a field out to keep it as it is; send null to clear it. The rules are the same as in Managing Deposit Accounts:

• status: you can switch between ENABLED and DISABLED. A disabled account stops crediting new top-ups, and they end up UNASSIGNED.
• BLOCKED and CLOSED are set only by Confirmo. A blocked account can't be changed by you (crypto_funding_account_status_not_changeable_by_merchant), so contact support. An account is CLOSED permanently when it can no longer be used, for example after your account moves to a different Confirmo entity. Create a new top-up account in that case.