TradingJuno
Guides

USDC Payouts

How to complete a USDC payout over Polygon, Stellar, and Solana.

You can execute the withdrawal in two different ways depending on whether you have created the receiving account in Bitso's system:

According to regulatory measures, Bitso asks you to comply with the Travel Rule (TR) when sending to or receiving from non-Bitso accounts digital assets in amounts greater than or equal to 1,000 euros (or equivalent in cryptocurrency).

Then, you must comply with the TR in either of the two different ways to execute a withdrawal. The only additional requirement for TR-compliant withdrawals is that the body of the call must include the mandatory TR compliance information (compliance object). When the digital assets you transfer are under 1,000 euros, your transaction does not need to comply with the Travel Rule.

The following examples depict transactions below the TR threshold. For examples above the threshold, see the article, Travel-Rule-Compliant USDC Payouts.

In Bitso, each withdrawal is associated with a taxonomy that identifies a currency, a method, and an integration with a payment gateway. You must always specify this metadata in your request body: asset, currency, method, network, and protocol. In addition, you need to set the address (destination) and chain parameters. In the case of Stellar, you also need the destination_tag.

🚀 You are ready to make your transaction when you have configured these parameters. To withdraw USDC funds from your Bitso account, complete the following HTTP request using the appropriate body parameters:

POST https://api-stage.bitso.com/v3/withdrawals

Body Parameters

  • amount: Number of funds to transfer in USDC. This value should be a positive number representing the monetary amount to be deducted from the Bitso account. Do not use commas when specifying your amount.
  • address: Destination address where the withdrawal is to be deposited.
  • asset: The digital asset transferred in a network. In most cases, it is the same as the withdrawal currency. However, for the USDC case, you must specify usdc.
  • contact_id: Bitso-generated, unique identifier of the beneficiary. You get this identifier back when you create the beneficiary in Bitso's system.
  • chain: Blockchain where transactions are processed. Supported values: POLY, xlm, and SOL.
  • currency: The currency to withdraw using the available balance. Supported value: usd.
  • destination_tag: Stellar names this field memo, and it indicates the specific wallet where the service will credit the deposit. You can either generate it programmatically, using programming languages and SDKs, or depending on the memo type, for example, memo_text, it's easy to do it manually. You can check the available types here. However, depending on the use case, the beneficiary might provide a memo to the sender. For instance, if the destination account is omnibus (concentrator), the beneficiary will likely have their own memo to receive deposits. It is a mandatory field in Bitso's Stellar implementation. This field was formerly named addressTag.
  • max_fee: Maximum fee, optional. It specifies the maximum amount that the user is willing to pay for the transaction. Because of the volatility of blockchain fees, they could be larger than the withdrawn amount. Setting a limit prevents high transaction fees.
  • method: Withdrawal method. Supported value: usdc_trf.
  • network: Payment network through which the withdrawal is processed. Supported value: circle.
  • origin_id: A client-generated unique value that the server uses to recognize subsequent retries of the same request. This idempotency key helps prevent duplicated withdrawals from being processed. Valid character set: a to z (lower and uppercase), 0 to 9, underscore, _. Dash, -, is not supported. Maximum length = 40 characters. This parameter is optional. Formerly, this field was called client_withdrawal_id, a name now deprecated and must not be used.
  • protocol: A specific mechanism, protocol, or standard used in a network to transfer funds. Supported value: usdc_trf.

Withdrawal Providing the Beneficiary's Digital Address

The following objects exemplify the body parameters used in the HTTP request to withdraw USDC funds under 1,000 euros or its equivalent in cryptocurrency over the different supported networks.

{       
    "asset": "usdc",
    "currency": "usd",    
    "method": "usdc_trf",
    "network": "circle",
    "protocol": "usdc_trf",
    "amount": "150",
    "address": "0x475888A0050A4F8098b3C812E1895A523FBB2FFF",
    "chain": "POLY",
    "max_fee": "0.015538100",
    "origin_id": "cffbb40c5900c395d9244fbb"
}
{       
    "asset": "usdc",
    "currency": "usd",    
    "method": "usdc_trf",
    "network": "circle",
    "protocol": "usdc_trf",
    "amount": "150",
    "address": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
    "destination_tag": "memo", 
    "chain": "xlm",
    "max_fee": "0.15538100",
    "origin_id": "1ffbb40c5900c395d9244fbb"
}
{       
    "asset": "usdc",
    "currency": "usd",    
    "method": "usdc_trf",
    "network": "circle",
    "protocol": "usdc_trf",
    "amount": "100",
    "address": "6mFCRksqQcKF7KcDNnNuSmiQmdq7k9CG6C19rZRc5jCq",
    "chain": "SOL",
    "max_fee": "0.0015",
    "origin_id": "00fbb40c5900c395d9244fbb"
}

Withdrawal Providing the Beneficiary's ID

For the case where you have already created the beneficiary, use the appropriate request body of the ones shown below, which exemplify a transfer for an amount smaller than 1,000 euros. The request body includes the variable contact_id, returned by the create contact call. When you set up a beneficiary, the system stores the transaction's taxonomy and the beneficiary's address.

If you don't have the contact ID, then retrieve your contacts list or do a filtered search. For more details, see the section, Retrieve Your Contacts List.

{
  "amount": "120",
  "origin_id": "cffbb40c5900c395d92dfed5",
  "max_fee": "0.015538100",
  "contact_id": 3399
}

Withdrawal Request Response

A successful withdrawal of funds returns the object shown below:

{
    "success": true,
    "payload": {
        "wid": "edc5d6f21c0914b433ab0ddadbbf029d",
        "status": "pending",
        "created_at": "2023-02-17T17:00:47+0000",
        "currency": "usd",
        "method": "usdc_trf",
        "method_name": "Circle Transfer",
        "amount": "150.00",
        "asset": "usdc",
        "network": "circle",
        "protocol": "usdc_trf",
        "integration": "circle-api",
        "details": {
            "origin_id": "cffbb40c5900c395d9244fbb",
            "tx_hash": "0x790b7b450ffbdc5b1dc1bdcc9b80436223824f9e186bfc83d761fe57fdffaed6",
            "withdrawal_address": "0x475888A0050A4F8098b3C812E1895A523FBB2FFF",
            "destination_tag": null,
            "chain": "POLY"
        }
    }
}
{
    "success": true,
    "payload": {
        "wid": "e2d0db6105b26ee9fc75cc97f2fc95ba",
        "status": "pending",
        "created_at": "2023-02-21T18:17:41+0000",
        "currency": "usd",
        "method": "usdc_trf",
        "method_name": "Circle Transfer",
        "amount": "150.00",
        "asset": "usdc",
        "network": "circle",
        "protocol": "usdc_trf",
        "integration": "circle-api",
        "details": {
            "origin_id": "1ffbb40c5900c395d9244fbb",
            "tx_hash": null,
            "withdrawal_address": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
            "destination_tag": "memo",
            "chain": "xlm"
        }
    }
}
{
    "success": true,
    "payload": {
        "wid": "c63158103ac1d470860ac09ab21c36c2",
        "status": "pending",
        "created_at": "2023-03-06T18:38:39+0000",
        "currency": "usd",
        "method": "usdc_trf",
        "method_name": "Circle Transfer",
        "amount": "100.00",
        "asset": "usdc",
        "network": "circle",
        "protocol": "usdc_trf",
        "integration": "circle-api",
        "details": {
            "origin_id": "00fbb40c5900c395d9244fbb",
            "tx_hash": null,
            "withdrawal_address": "6mFCRksqQcKF7KcDNnNuSmiQmdq7k9CG6C19rZRc5jCq",
            "destination_tag": null,
            "chain": "SOL"
        }
    }

Getting a Withdrawal's Details

The payload returned by the create withdrawal call includes the variable wid, which stores the identifier of the transaction. This ID can help you track the transaction by making the following HTTP call, which returns detailed information on a user's funds withdrawal:

GET https://api-stage.bitso.com/v3/withdrawals/{wid}

If you do not specify a withdrawal identifier, then it lists all of your withdrawals.

Another variable included in the payload is status, which reports the withdrawal's state. Withdrawals can be in one of four possible states:

  • PENDING: Bitso is currently processing the withdrawal request and has not sent the transaction to the blockchain. The system found enough balance to fund the payout from your wallet, so it has created the transaction and has set this initial status.
  • PROCESSING: Bitso sent the withdrawal to the blockchain and it is being processed there, yet to be validated by the network.
  • COMPLETE: The blockchain network validated the withdrawal; the funds are now in the target wallet or account.
  • FAILED: The system could not complete the withdrawal; the funds remain in the original wallet or account.

Successful retrieval of a withdrawal's details returns the response object shown below.

{
    "success": true,
    "payload": [
        {
            "wid": "edc5d6f21c0914b433ab0ddadbbf029d",
            "status": "processing",
            "created_at": "2023-02-17T17:00:47+0000",
            "currency": "usd",
            "method": "usdc_trf",
            "method_name": "Circle Transfer",
            "amount": "150.00",
            "asset": "usdc",
            "network": "circle",
            "protocol": "usdc_trf",
            "integration": "circle-api",
            "details": {
                "origin_id": "cffbb40c5900c395d9244fbb",
                "tx_hash": "Unknown",
                "withdrawal_address": "0x475888A0050A4F8098b3C812E1895A523FBB2FFF",
                "destination_tag": null,
                "chain": "POLY"
            },
            "legal_operation_entity": {
                "name": "Bitso International",
                "country_code_iso_2": "GI",
                "image_id": "bitso"
            }
        }
    ]
}
{
    "success": true,
    "payload": [
        {
            "wid": "e2d0db6105b26ee9fc75cc97f2fc95ba",
            "status": "complete",
            "created_at": "2023-02-21T18:17:41+0000",
            "currency": "usd",
            "method": "usdc_trf",
            "method_name": "Circle Transfer",
            "amount": "150.00",
            "asset": "usdc",
            "network": "circle",
            "protocol": "usdc_trf",
            "integration": "circle-api",
            "details": {
                "origin_id": "1ffbb40c5900c395d9244fbb",
                "tx_hash": "0570accf800a204597e47380246e68e07f951b4d4a8501b0c7a156c13e8b664e",
                "withdrawal_address": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
                "destination_tag": "memo",
                "chain": "XLM"
              },
            "legal_operation_entity": {
                "name": "Bitso International",
                "country_code_iso_2": "GI",
                "image_id": "bitso"
            }
        }
    ]
}
{
    "success": true,
    "payload": [
        {
            "wid": "c63158103ac1d470860ac09ab21c36c2",
            "status": "processing",
            "created_at": "2023-03-06T18:38:39+00:00",
            "currency": "usd",
            "method": "usdc_trf",
            "method_name": "Circle Transfer",
            "amount": "100.00",
            "asset": "usdc",
            "network": "circle",
            "protocol": "usdc_trf",
            "integration": "circle-api",
            "details": {
                "origin_id": "00fbb40c5900c395d9244fbb",
                "tx_hash": null,
                "withdrawal_address": "6mFCRksqQcKF7KcDNnNuSmiQmdq7k9CG6C19rZRc5jCq",
                "destination_tag": null,
                "chain": "SOL"
            },
            "legal_operation_entity": {
                "name": "Bitso International",
                "country_code_iso_2": "GI",
                "image_id": "bitso"
            }
        }
    ]
}

Updated 8 months ago

Did this page help you?