Mint

Burn Tokens

Overview

You can burn tokens by creating an order with the token as the source and the funding asset as the destination. Burning permanently removes tokens from circulation and returns the equivalent backing asset, keeping reserves 1:1.

All burn orders go through validation, authorization, and reconciliation controls to ensure that redeemed tokens are fully removed from supply and align with reserve balances.

Prerequisites

Get Started
- Access token must have either the wallet_spend or wallet_spend_all scopes.
- User role must have spend permissions.
Add a wallet user
Accept the Minting Services Terms
Deposit Assets

Cookbook

Want the steps without the walkthrough? Expand the cookbook below:

Track OrdersOpen Cookbook

1. Configure HMAC

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:

const crypto = require('crypto-js');

const rawToken = pm.environment.get('BITGO_ACCESS_TOKEN');
const url = new URL(pm.request.url.toString());

// Include query params in the path (auth-service uses x-original-uri, which includes them).
const urlPath = url.pathname + url.search;

// GET requests have no body; POST/PUT and others need compact JSON.
let body = '';
if (pm.request.method !== 'GET' && pm.request.body && pm.request.body.raw) {
  body = JSON.stringify(JSON.parse(pm.request.body.raw));
}

const timestamp = Date.now().toString();

// v2 HMAC subject: timestamp|urlPath|body
const subject = [timestamp, urlPath, body].join('|');
const hmac = crypto.HmacSHA256(subject, rawToken).toString(crypto.enc.Hex);
const tokenHash = crypto.SHA256(rawToken).toString(crypto.enc.Hex);

pm.request.headers.upsert({ key: 'Authorization', value: 'Bearer ' + tokenHash });
pm.request.headers.upsert({ key: 'auth-timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'bitgo-auth-version', value: '2.0' });
pm.request.headers.upsert({ key: 'hmac', value: hmac });

2. List Supported Tokens

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.

Endpoint: Get supported tokens for an enterprise

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"

curl -X GET \
  "https://app.bitgo-test.com/api/mint/v1/enterprise/$ENTERPRISE_ID/supported-tokens" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \

Step Result

{
  "tokens": [
    {
      "token": "usd1",
      "assets": [
        "sol:usd1",
        "eth:usd1",
        "bsc: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

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.

Endpoint: Get supported asset pairs

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export COIN="<ASSET_ID>"

curl -X GET \
  "https://app.bitgo-test.com/api/mint/v1/enterprise/$ENTERPRISE_ID/asset-pairs" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \

Step Result

{
  "assetPairs": [
    {
      "source": { 
        "asset": "sol:usd1", 
        "minimumAmount": "100", 
        "decimals": 2 
      },
      "destination": { 
        "asset": "tfiatusd", 
        "decimals": 2 
      },
      "fee": { 
        "basisPoints": "10" 
      }
    }
  ]
}

4. Calculate Base Units

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 * 10^Decimals

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

# 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"

const fromAmount = (100 * Math.pow(10, stablecoinAsset.decimals)).toString(); // 100 stablecoin in base units

5. Create Burn Order

Endpoint: Create an order

```shell cURL
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export COIN="<ASSET_ID>"
export SOURCE_WALLET_ID="<YOUR_WALLET_ID>"
export DESTINATION_WALLET_ID="<DESTINATION_WALLET_ID>"

curl -X POST \
  "https://app.bitgo-test.com/enterprise/$ENTERPRISE_ID/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-enterprise-id: $ENTERPRISE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "<YOUR_UNIQUE_KEY>",
    "source": {
      "asset":    "<ASSET_ID>",
      "amount":   "100000000",
      "walletId": "'"$SOURCE_WALLET_ID"'",
      "type":     "GO_ACCOUNT"
    },
    "destination": {
      "asset":    "<ASSET_ID>",
      "type":     "GO_ACCOUNT",
      "walletId": "'"$DESTINATION_WALLET_ID"'"
    }
  }'

Burn Status Lifecycle

Status	Description
`CREATED`	Order created and awaiting the token deposit.
`CONFIRMED_DEPOSIT`	Token deposit detected.
`PROCESSING`	The burn is being executed and settled.
`FULFILLED`	Tokens burned and the funding asset delivered to the destination.
`FAILED`	The order could not be completed.
`CANCELLED`	The order was cancelled.

Step Result

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

The following example shows the minimum required parameters for burning an asset.

Endpoint: Send Transaction

export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
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"'" // This is the id from the Create Mint Order results.
}'

const wallet = await bitgo.coin('$COIN').wallets().get({ id: walletId });
  await wallet.sendMany({
    recipients: [{ address: treasuryWalletId, amount: fromAmount }],
    sequenceId: order.id,
    walletPassphrase,
  });

Step Result

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

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

Endpoint: Get an order by ID

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" \

Step Result

{
  "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)

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.

Endpoint: List orders

curl -X GET \
  "https://app.bitgo-test.com/enterprise/$ENTERPRISE_ID/orders" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \

Step Result

{
  "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
}

Burn Tokens

Overview

Prerequisites

Cookbook

1. Configure HMAC

2. List Supported Tokens

Step Result

3. List Asset Pairs

Step Result

4. Calculate Base Units

5. Create Burn Order

Step Result

6. Send Burn Order

Step Result

7. Check Order Status

Step Result

8. Bulk Fetch Orders by ID (Optional)

Step Result

See Also