Burn Tokens

Burn tokens by creating an order with the token as source and the funding asset as destination. See the Guide.

  1. The Mint API uses BitGo v2 HMAC authentication. To generate the hmac header dynamically, create an environment with the variable BITGO_ACCESS_TOKEN set to your access token, then add the following pre-request script:

  2. View the tokens available to your enterprise, including burn minimums, fees, and your role for each token. The response includes the chain-scoped asset IDs you need when choosing an asset pair and creating the order. The following example passes the testnet base URL and returns testnet asset IDs. To see production asset IDs, call the production base URL (https://app.bitgo.com).

    API Reference

  3. List the available asset pairs for your enterprise and find the pair where source is the token you want to burn and destination is the funding asset you want to receive. The following example passes the testnet base URL and returns testnet asset IDs. To see production asset IDs, call the production base URL (https://app.bitgo.com).

    API Reference

  4. Express the amount of tokens to burn in base units. Use the source.decimals value from the previous step to convert your full-unit amount to base units. Formula: Base Units = Amount * 10Decimals Example (token): A redemption of 100 tokens occurs for an asset with 6 decimals:

    • Amount: 100
    • Decimals: 6
    • Calculation: 100 * 10⁶ = 100,000,000
    • Result: 100,000,000 base units
  5. The following example shows the minimum required parameters for burning an asset.

    API Reference

  6. Retrieve the real-time status and detailed metadata for the burn order. Poll this endpoint until the order reaches FULFILLED or FAILED.

    API Reference

  7. Repeat the id parameter to fetch a specific set of orders in one call. This is the efficient way to refresh many known orders at once.

    API Reference

// 1. Configure HMAC
// Use the JavaScript tab for this step
// 2. List Supported Tokens
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/api/mint/v1/enterprise/$ENTERPRISE_ID/supported-tokens \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 3. List Asset Pairs
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/api/mint/v1/enterprise/$ENTERPRISE_ID/asset-pairs \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 4. Calculate Base Units
# Calculate programmatically  
DECIMALS=6  # From assets API response for stablecoin
AMOUNT_BASE_UNITS=$(($AMOUNT_IN_FULL_UNITS * 10**$DECIMALS))
echo "Amount in base units: $AMOUNT_BASE_UNITS"
// 5. Create Burn Order
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export IDEMPOTENCY_KEY="<YOUR_IDEMPOTENCY_KEY>"
export SOURCE_ASSET="<ASSET_ID>"
export SOURCE_AMOUNT="<SOURCE_AMOUNT>"
export SOURCE_WALLET_ID="<YOUR_WALLET_ID>"
export DESTINATION_ASSET="<DESTINATION_ASSET>"
export DESTINATION_WALLET_ID="<DESTINATION_WALLET_ID>"

curl -X POST \
  https://app.bitgo-test.com/enterprise/$ENTERPRISE_ID/orders \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "idempotencyKey": "'""$IDEMPOTENCY_KEY""'",
    "source": {
      "asset":    "'"$SOURCE_ASSET"'",
      "amount":   "'"$SOURCE_AMOUNT"'",
      "walletId": "'"$SOURCE_WALLET_ID"'",
      "type":     "GO_ACCOUNT"
    },
    "destination": {
      "asset":    "'"$DESTINATION_ASSET"'",
      "walletId": "'"$DESTINATION_WALLET_ID"'",
      "type":     "GO_ACCOUNT"
    }
  }'
// 6. Send Burn Order
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ADDRESS="<ADDRESS>"
export AMOUNT="<AMOUNT>"
export WALLET_PASSPHRASE="<YOUR_WALLET_PASSPHRASE>"
export SEQUENCE_ID="<ORDER_ID>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST/api/v2/$COIN/wallet/$WALLET_ID/sendcoins \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "address": "'"$ADDRESS"'",
    "amount": "'"$AMOUNT"'",
    "walletPassphrase": "'"$WALLET_PASSPHRASE"'",
    "sequenceId": "'"$SEQUENCE_ID"'"    # The ID from the Create Mint Order results
}'
// 7. Check Order Status
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ORDER_ID="<YOUR_ORDER_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/enterprise/$ENTERPRISE_ID/orders/$ORDER_ID \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 8. Bulk Fetch Orders by ID (Optional)
curl -X GET \
  https://app.bitgo-test.com/enterprise/$ENTERPRISE_ID/orders \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
// 2. List Supported Tokens Response
{
  "tokens": [
    {
      "token": "usd1",
      "assets": [
        "tsol:usd1",
        "hteth:usd1",
        "tbsc:usd1"
      ],
      "type": "stablecoin",
      "minimumMintAmount": "1.5",
      "minimumBurnAmount": "1.5",
      "mintFeeBps": "5",
      "burnFeeBps": "5",
      "description": "A stablecoin backed by US dollar reserves",
      "role": "issuer",
      "issuerOrdersEnabled": true,
      "name": "USD1"
    }
  ]
}
// 3. List Asset Pairs Response
{
  "assetPairs": [
    {
      "source": { 
        "asset": "tsol:usd1", 
        "minimumAmount": "100", 
        "decimals": 2 
      },
      "destination": { 
        "asset": "tfiatusd", 
        "decimals": 2 
      },
      "fee": { 
        "basisPoints": "10" 
      }
    }
  ]
}
// 5. Create Burn Order Response
{
  "id": "95bdbd9c-9cdc-41a4-ae70-165387b7aa51",
  "userId": "user-123",
  "status": "CREATED",
  "enterpriseId": "67bc4ae090e8af8f9b412d3d67e85252",
  "source":      { 
    "asset": "tfiatusd", 
    "amount": "100000000", 
    "type": "GO_ACCOUNT", 
    "walletId": "67bc4b03..." 
    },
  "destination": { 
    "asset": "hteth:usd1", 
    "type": "GO_ACCOUNT", 
    "address": "0x123456789abcdef123456789abcdef123456789a",
    "walletId": "67bc4b038f5408faefbfc8edcf6e6577",
    "transferId": "6437d9f07d6a87000613e6c06e4218d3",
    },
  "createdAt": "string",
  "updatedAt": "string",
  "idempotencyKey": "mint-order-2025-04-04-001",
  "depositInstructions": {
    "type": "GO_ACCOUNT",
    "asset": "string",
    "sequenceId": "order-deposit:95bdbd9c-9cdc-41a4-ae70-165387b7aa51",
    "address": "0x123456789abcdef123456789abcdef123456789a"
  },
  "createdAt": "2025-04-04T09:25:48.216Z",
  "updatedAt": "2025-04-04T09:25:48.216Z"
}
// 6. Send Burn Order Response
{
  "coin": "ofchteth:usd1",
  "transfers": [
    {
      "id": "transfer_id_12345",
      "coin": "ofchteth:usd1",
      "wallet": "67bc4b03...",
      "value": -10000,
      "baseValue": -10000,
      "state": "unconfirmed",
      "type": "send"
    }
  ]
}
// 7. Check Order Status Response
{
  "timeline": [
    {
      "status": "PROCESSING",
      "timestamp": "2025-04-04T09:25:48.216Z"
    }
  ],
  "transactions": [
    {
      "type": "DEPOSIT",
      "status": "INITIATED",
      "asset": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "transactionHash": "string",
      "transferId": "string",
      "amount": "500000000"
    }
  ],
  "id": "string",
  "userId": "string",
  "type": "BURN",
  "status": "CREATED",
  "enterpriseId": "string",
  "source": {
    "asset": "string",
    "amount": "string",
    "type": "GO_ACCOUNT",
    "walletId": "string"
  },
  "destination": {
    "asset": "string",
    "type": "GO_ACCOUNT",
    "amount": "string",
    "address": "0x123456789abcdef123456789abcdef123456789a",
    "walletId": "67bc4b038f5408faefbfc8edcf6e6577",
    "transferId": "6437d9f07d6a87000613e6c06e4218d3",
    "transactionHash": "0xdeadbeef..."
  },
  "fee": {
    "basisPoints": "5"
  },
  "createdAt": "string",
  "updatedAt": "string",
  "idempotencyKey": "mint-order-2025-04-04-001",
  "depositInstructions": {
    "type": "GO_ACCOUNT",
    "asset": "string",
    "sequenceId": "order-deposit:95bdbd9c-9cdc-41a4-ae70-165387b7aa51",
    "address": "0x123456789abcdef123456789abcdef123456789a"
  },
}
// 8. Bulk Fetch Orders by ID (Optional) Response
{
  "orders": [
    {
      "id": "string",
      "userId": "string",
      "type": "BURN",
      "status": "CREATED",
      "enterpriseId": "string",
      "source": {
        "asset": "string",
        "amount": "string",
        "type": "GO_ACCOUNT",
        "walletId": "string"
      },
      "destination": {
        "asset": "string",
        "type": "GO_ACCOUNT",
        "amount": "string",
        "address": "0x123456789abcdef123456789abcdef123456789a",
        "walletId": "67bc4b038f5408faefbfc8edcf6e6577",
        "transferId": "6437d9f07d6a87000613e6c06e4218d3",
        "transactionHash": "0xdeadbeef..."
      },
      "fee": {
        "basisPoints": "5"
      },
      "createdAt": "string",
      "updatedAt": "string",
      "idempotencyKey": "mint-order-2025-04-04-001",
      "depositInstructions": {
        "type": "GO_ACCOUNT",
        "asset": "string",
        "sequenceId": "order-deposit:95bdbd9c-9cdc-41a4-ae70-165387b7aa51",
        "address": "0x123456789abcdef123456789abcdef123456789a"
      },
      "orderMethod": "ISSUER_DIRECT",
      "memo": "string"
    }
  ],
  "total": 142,
  "pageNo": 1,
  "pageSize": 50
}