From 657817f2dcdc7c8669ca357cd7ebdf3c887c8773 Mon Sep 17 00:00:00 2001 From: Sachu Shaji Abraham Date: Tue, 19 Aug 2025 16:45:36 +0530 Subject: [PATCH] docs: add API documentation for mint and burn workflows this change adds API Documentation for mints and burn workflows Ticket: TMS-1404 --- .../ts/stablecoin/STABLECOIN_API_GUIDE.md | 399 ++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 examples/ts/stablecoin/STABLECOIN_API_GUIDE.md diff --git a/examples/ts/stablecoin/STABLECOIN_API_GUIDE.md b/examples/ts/stablecoin/STABLECOIN_API_GUIDE.md new file mode 100644 index 0000000000..d0afa4c13f --- /dev/null +++ b/examples/ts/stablecoin/STABLECOIN_API_GUIDE.md @@ -0,0 +1,399 @@ +# BitGo Stablecoin API Documentation + +This documentation provides comprehensive API-only workflows for creating stablecoin mint and burn orders using curl commands. These examples are based on the TypeScript implementations but provide pure HTTP API interactions. + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Setup BitGo Express](#setup-bitgo-express) +3. [Environment Variables](#environment-variables) +4. [Mint Order Process](#mint-order-process) +5. [Burn Order Process](#burn-order-process) +6. [GoAccount Transfers via BitGo Express](#goaccount-transfers-via-bitgo-express) + +## Prerequisites + +- BitGo API access token +- Enterprise ID +- Wallet ID (GoAccount) +- Wallet passphrase +- BitGo Express server running locally + +## Setup BitGo Express + +BitGo Express is required for GoAccount transfers. You can install it via npm or Docker (recommended). + +### Option 1: Install via Docker (Recommended) + +Docker is the recommended way to run BitGo Express as it ensures continuous feature parity and security updates. + +**Prerequisites:** + +- Docker installed on your system + +**Pull and run BitGo Express:** + +```bash +# Pull the latest Docker container +docker pull bitgo/express:latest + +# Run for testnet (default) +docker run -it -p 3080:3080 bitgo/express:latest + +# Run for production +docker run -it -p 3080:3080 bitgo/express:latest --env prod + +# Run on custom port +docker run -it -p 4000:4000 bitgo/express:latest --port 4000 +``` + +### Option 2: Install via NPM + +```bash +npm install -g @bitgo/express +``` + +**Start BitGo Express:** + +```bash +# For testnet +bitgo-express --port 3080 --env test --bind localhost + +# For production +bitgo-express --port 3080 --env prod --bind localhost +``` + +### Verify BitGo Express is Running + +```bash +curl -X GET http://localhost:3080/api/v2/ping +``` + +**Expected Response:** + +```json +{ + "status": "service is ok!", + "environment": "BitGo Testnet", + "configEnv": "testnet" +} +``` + +## Environment Variables + +Set up your environment variables: + +```bash +# API Configuration +export BITGO_ENV="test" # or "prod" for production +export ACCESS_TOKEN="your_access_token_here" +export ENTERPRISE_ID="your_enterprise_id_here" +export WALLET_ID="your_goaccount_wallet_id_here" +export WALLET_PASSPHRASE="your_wallet_passphrase_here" + +# BitGo Express +export BITGO_EXPRESS_HOST="localhost:3080" + +# Asset Configuration +export USD_ASSET="tfiatusd" # USD asset token (testnet) +export STABLECOIN_ASSET="tbsc:usd1" # Stablecoin to mint/burn (testnet) +export OFC_USD_COIN="ofctusd" # OFC USD for transfers +export OFC_STABLECOIN="ofctbsc:usd1" # OFC stablecoin for transfers + +# Amount Configuration (in full units) +export AMOUNT_IN_FULL_UNITS="100" # Amount to mint/burn +``` + +## Mint Order Process + +The mint order process converts USD to stablecoin through the following steps: + +### Mint Step 1: Get Available Assets + +```bash +curl -X GET \ + "https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/assets" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" +``` + +**Optional Query Parameters:** +- `ids`: Filter by specific asset IDs (comma-separated UUIDs) +- `token`: Filter by token symbol (e.g., `eth:usd1`) +- `chain`: Filter by blockchain network (e.g., `eth`, `bsc`) + +**Example with filters:** +```bash +# Get assets for specific chain +curl -X GET \ + "https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/assets?chain=tbsc" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" +``` + +Expected Response: + +```json +[ + { + "id": "08c1271e-b15d-4af8-8929-f75383903da4", + "token": "tfiatusd", + "name": "Testnet US Dollar", + "decimals": 2, + }, + { + "id": "bfd0daec-f849-4b96-bdb6-6373bffeb9b6", + "token": "tbsc:usd1", + "name": "Testnet BSC USD1", + "decimals": 18, + "chain": "tbsc", + "backingAsset": "tfiatusd", + "treasuryAccountWalletId": "67c1a025f9999f485f7a71aa26a1da4c" + }, + { + "id": "49ff49ea-3355-4717-bbb0-5e8f5cae2202", + "token": "hteth:gousd", + "name": "Testnet goUSD", + "decimals": 6, + "chain": "hteth", + "backingAsset": "tfiatusd", + "treasuryAccountWalletId": "6698e670115059e2efe672436a3aea3b" + } +] +``` + +### Mint Step 2: Calculate Amount in Base Units + +For USD with 2 decimals and amount of 100: + +- Base units = 100 × 10² = 10000 + +```bash +# Calculate programmatically +DECIMALS=2 # From assets API response +AMOUNT_BASE_UNITS=$((${AMOUNT_IN_FULL_UNITS} * 10**${DECIMALS})) +echo "Amount in base units: ${AMOUNT_BASE_UNITS}" +``` + +### Mint Step 3: Create Mint Order + +```bash +curl -X POST \ + "https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/order" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -d '{ + "sourceWalletId": "'${WALLET_ID}'", + "destinationWalletId": "'${WALLET_ID}'", + "destinationType": "go_account", + "fromAssetId": "usd_asset_id_from_step1", + "toAssetId": "stablecoin_asset_id_from_step1", + "fromAmount": "'${AMOUNT_BASE_UNITS}'", + "type": "mint" + }' +``` + +Expected Response: + +```json +{ + "id": "order_id_12345", + "type": "mint", + "status": "pending_funding", + "fromAssetId": "usd_asset_id", + "toAssetId": "stablecoin_asset_id", + "fromAmount": "10000", + "sourceWalletId": "wallet_id", + "destinationWalletId": "wallet_id", + "createdAt": "2025-08-19T10:00:00.000Z" +} +``` + +### Mint Step 4: Transfer USD to Treasury (via BitGo Express) + +```bash +curl -X POST \ + "http://${BITGO_EXPRESS_HOST}/api/v2/${OFC_USD_COIN}/wallet/${WALLET_ID}/sendcoins" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -d '{ + "address": "'${TREASURY_WALLET_ID}'", + "amount": "'${AMOUNT_BASE_UNITS}'", + "walletPassphrase": "'${WALLET_PASSPHRASE}'", + "sequenceId": "'${ORDER_ID}'" + }' +``` + +Expected Response: + +```json +{ + "coin": "ofctusd", + "transfers": [ + { + "id": "transfer_id_12345", + "coin": "ofctusd", + "wallet": "source_wallet_id", + "value": -10000, + "baseValue": -10000, + "state": "unconfirmed", + "type": "send" + } + ] +} +``` + +### Mint Step 5: Check Order Status + +```bash +curl -X GET \ + "https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/orders/${ORDER_ID}" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" +``` + +Expected Response: + +```json +{ + "id": "order_id_12345", + "type": "mint", + "status": "completed", + "fromAssetId": "usd_asset_id", + "toAssetId": "stablecoin_asset_id", + "fromAmount": "10000", + "toAmount": "100000000", + "completedAt": "2025-08-19T10:05:00.000Z" +} +``` + +## Burn Order Process + +The burn order process converts stablecoin back to USD: + +### Burn Step 1: Get Available Assets + +Same as mint process step 1. + +### Burn Step 2: Get Treasury Wallet ID + +The treasury wallet ID is included in the assets API response from step 1, in the `treasuryAccountWalletId` field of the stablecoin asset. + +### Burn Step 3: Calculate Amount in Base Units + +For stablecoin with 6 decimals and amount of 100: + +- Base units = 100 × 10⁶ = 100000000 + +```bash +# 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}" +``` + +### Burn Step 4: Create Burn Order + +```bash +curl -X POST \ + "https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/order" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -d '{ + "sourceWalletId": "'${WALLET_ID}'", + "destinationWalletId": "'${WALLET_ID}'", + "destinationType": "go_account", + "fromAssetId": "stablecoin_asset_id_from_step1", + "toAssetId": "usd_asset_id_from_step1", + "fromAmount": "'${AMOUNT_BASE_UNITS}'", + "type": "burn" + }' +``` + +### Burn Step 5: Transfer Stablecoin to Treasury (via BitGo Express) + +```bash +curl -X POST \ + "http://${BITGO_EXPRESS_HOST}/api/v2/${OFC_STABLECOIN}/wallet/${WALLET_ID}/sendcoins" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -d '{ + "address": "'${TREASURY_WALLET_ID}'", + "amount": "'${AMOUNT_BASE_UNITS}'", + "walletPassphrase": "'${WALLET_PASSPHRASE}'", + "sequenceId": "'${ORDER_ID}'" + }' +``` + +### Burn Step 6: Check Order Status + +Same as mint process step 5. + +## GoAccount Transfers via BitGo Express + +### Prerequisites for GoAccount Transfers + +1. **BitGo Express Setup**: BitGo Express must be running locally +2. **OFC Asset**: Use the "ofc" prefixed version of your asset (e.g., `ofctusd` for USD transfers) +3. **Address Parameter**: For treasury transfers and most GoAccount operations, use `address` parameter with the destination wallet ID + +### Transfer Parameters + +| Parameter | Description | Required | +|-----------|-------------|----------| +| `address` | Destination wallet ID or external address | Yes | +| `walletId` | Alternative to address for GoAccount transfers (context-dependent) | No | +| `amount` | Amount in base units | Yes | +| `walletPassphrase` | Source wallet passphrase | Yes | +| `sequenceId` | Unique identifier (use order ID) | Yes | + + +## API Endpoints Reference + +### Stablecoin API Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/stablecoin/v1/assets` | List available assets (includes treasury wallet IDs) | +| POST | `/api/stablecoin/v1/enterprise/{enterpriseId}/order` | Create order | +| GET | `/api/stablecoin/v1/enterprise/{enterpriseId}/orders/{orderId}` | Get order details | + +### BitGo Express Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v2/ping` | Health check | +| POST | `/api/v2/{coin}/wallet/{walletId}/sendmany` | Send to multiple recipients | + +### Base URLs + +- **Testnet**: `https://app.bitgo-test.com` +- **Production**: `https://app.bitgo.com` +- **BitGo Express**: `http://localhost:3080` (default) + +## Security Considerations + +1. **API Keys**: Store access tokens securely, never commit to version control +2. **Wallet Passphrases**: Use environment variables, avoid hardcoding +3. **Network Security**: Use HTTPS for all API calls + +## Troubleshooting + +### Common Issues + +1. **BitGo Express Not Running**: Ensure Express server is started and accessible +2. **Invalid Asset IDs**: Verify asset IDs from the assets API response +3. **Insufficient Balance**: Check wallet balance before initiating transfers +4. **Wrong Environment**: Ensure consistent use of test/prod environments +5. **Sequence ID Conflicts**: Use unique sequence IDs for each transaction + +### Debug Commands + +```bash +# Check BitGo Express status +curl -X GET http://localhost:3080/api/v2/ping +``` + +--- + +This documentation provides a complete API-only workflow for BitGo stablecoin operations. For additional support, refer to the [BitGo API Documentation](https://developers.bitgo.com/) or contact BitGo support.