Stablecoin Deposits

This tutorial outlines how to deposit stablecoins (USDC/USDT) into your Caliza account. Unlike fiat deposits, this flow involves interacting with the blockchain and manually confirming the transaction hash to link the deposit to your account.

Step 1: Simulate the Deposit

Before moving funds, you must simulate the deposit. This step validates the currency pair and the funding method. Use the Simulate transaction or payment endpoint to do so:

curl --location 'https://api.sandbox.caliza.com/core-api/v1/simulations' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{beneficiaryId}}",
  "from": {
    "value": 10,
    "currencyCode": "USDC"
  },
  "to": {
    "currencyCode": "USDC"
  },
  "fundingMethod": "ETH"
}'

{
  "id": "34c9dfe7-12da-4119-8beb-4db895c01a47",
  "integratorId": "...",
  "beneficiaryId": "...",
  "from": {
    "currencyCode": "USDC",
    "value": 10.00
  },
  "to": {
    "currencyCode": "USDC",
    "value": 10.00
  },
  "fundingMethod": "ETH",
  ...
}

The API returns a simulation object. Copy the id field (Simulation ID) to proceed.

Step 2: Get the Funding Wallet

Create the transaction record using the simulation ID. This step is required to retrieve the specific wallet address where the funds must be sent.

To do so, send a POST request to the /v1/transactions endpoint:

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
   "simulationId": "{{simulationId}}",
   "beneficiaryIp": "127.0.0.1"
}'

{
  "id": "5d097212-9902-4d86-beec-c578640105f4",
  "status": "PENDING",
  "blockchainInfo": {
    "fundingWallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "depositTransactionHash": null
  },
  ...
}

Look for the blockchainInfo object. The fundingWallet field contains the destination address.

Step 3: Transfer Funds (On-Chain)

Perform the actual crypto transfer using your external wallet (for example, MetaMask, Ledger, or an Exchange).

• Destination: The address found in blockchainInfo.fundingWallet.
• Amount: Must match the from.value specified in the simulation.
• Network: Make sure you use the network corresponding to the fundingMethod (for example, Ethereum for ETH).

Once the transfer is broadcast to the network, copy the Transaction Hash (TXID).

Step 4: Attach Transaction Hash

Send a PUT request to the /v1/transactions/{id}/depositTransactionHash to verify the deposit, you need to explicitly link the blockchain transaction hash to the Caliza transaction ID. This enables Caliza to match your deposit with the funds received in the wallet.

See the example below:

curl --location --request PUT 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{transaction_id}}/depositTransactionHash' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
   "transactionHash": "0x_YOUR_BLOCKCHAIN_TX_HASH"
}'

Monitor Completion

After attaching the hash, Caliza monitors the blockchain for confirmations. Once confirmed, the transaction status updates to SUCCEEDED.

Check Balance

You can verify that the funds have been credited to the beneficiary's balance using the balances endpoint.

curl --location 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{beneficiaryId}}/balances?currency=USDC' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json'

{
  "currencyCode": "USDC",
  "availableBalance": 10.00,
  "pendingBalance": 0.00
}

Related Articles