Skip to content

Commit 61472d4

Browse files
sachushajisachushaji
authored
docs: add API documentation for mint and burn workflows
2 parents a204fb5 + 657817f commit 61472d4

File tree

1 file changed

+399
-0
lines changed

1 file changed

+399
-0
lines changed

‎examples/ts/stablecoin/STABLECOIN_API_GUIDE.md‎

Lines changed: 399 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,399 @@
1+
# BitGo Stablecoin API Documentation
2+
3+
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.
4+
5+
## Table of Contents
6+
7+
1. [Prerequisites](#prerequisites)
8+
2. [Setup BitGo Express](#setup-bitgo-express)
9+
3. [Environment Variables](#environment-variables)
10+
4. [Mint Order Process](#mint-order-process)
11+
5. [Burn Order Process](#burn-order-process)
12+
6. [GoAccount Transfers via BitGo Express](#goaccount-transfers-via-bitgo-express)
13+
14+
## Prerequisites
15+
16+
- BitGo API access token
17+
- Enterprise ID
18+
- Wallet ID (GoAccount)
19+
- Wallet passphrase
20+
- BitGo Express server running locally
21+
22+
## Setup BitGo Express
23+
24+
BitGo Express is required for GoAccount transfers. You can install it via npm or Docker (recommended).
25+
26+
### Option 1: Install via Docker (Recommended)
27+
28+
Docker is the recommended way to run BitGo Express as it ensures continuous feature parity and security updates.
29+
30+
**Prerequisites:**
31+
32+
- Docker installed on your system
33+
34+
**Pull and run BitGo Express:**
35+
36+
```bash
37+
# Pull the latest Docker container
38+
docker pull bitgo/express:latest
39+
40+
# Run for testnet (default)
41+
docker run -it -p 3080:3080 bitgo/express:latest
42+
43+
# Run for production
44+
docker run -it -p 3080:3080 bitgo/express:latest --env prod
45+
46+
# Run on custom port
47+
docker run -it -p 4000:4000 bitgo/express:latest --port 4000
48+
```
49+
50+
### Option 2: Install via NPM
51+
52+
```bash
53+
npm install -g @bitgo/express
54+
```
55+
56+
**Start BitGo Express:**
57+
58+
```bash
59+
# For testnet
60+
bitgo-express --port 3080 --env test --bind localhost
61+
62+
# For production
63+
bitgo-express --port 3080 --env prod --bind localhost
64+
```
65+
66+
### Verify BitGo Express is Running
67+
68+
```bash
69+
curl -X GET http://localhost:3080/api/v2/ping
70+
```
71+
72+
**Expected Response:**
73+
74+
```json
75+
{
76+
"status": "service is ok!",
77+
"environment": "BitGo Testnet",
78+
"configEnv": "testnet"
79+
}
80+
```
81+
82+
## Environment Variables
83+
84+
Set up your environment variables:
85+
86+
```bash
87+
# API Configuration
88+
export BITGO_ENV="test" # or "prod" for production
89+
export ACCESS_TOKEN="your_access_token_here"
90+
export ENTERPRISE_ID="your_enterprise_id_here"
91+
export WALLET_ID="your_goaccount_wallet_id_here"
92+
export WALLET_PASSPHRASE="your_wallet_passphrase_here"
93+
94+
# BitGo Express
95+
export BITGO_EXPRESS_HOST="localhost:3080"
96+
97+
# Asset Configuration
98+
export USD_ASSET="tfiatusd" # USD asset token (testnet)
99+
export STABLECOIN_ASSET="tbsc:usd1" # Stablecoin to mint/burn (testnet)
100+
export OFC_USD_COIN="ofctusd" # OFC USD for transfers
101+
export OFC_STABLECOIN="ofctbsc:usd1" # OFC stablecoin for transfers
102+
103+
# Amount Configuration (in full units)
104+
export AMOUNT_IN_FULL_UNITS="100" # Amount to mint/burn
105+
```
106+
107+
## Mint Order Process
108+
109+
The mint order process converts USD to stablecoin through the following steps:
110+
111+
### Mint Step 1: Get Available Assets
112+
113+
```bash
114+
curl -X GET \
115+
"https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/assets" \
116+
-H "Content-Type: application/json" \
117+
-H "Authorization: Bearer ${ACCESS_TOKEN}"
118+
```
119+
120+
**Optional Query Parameters:**
121+
- `ids`: Filter by specific asset IDs (comma-separated UUIDs)
122+
- `token`: Filter by token symbol (e.g., `eth:usd1`)
123+
- `chain`: Filter by blockchain network (e.g., `eth`, `bsc`)
124+
125+
**Example with filters:**
126+
```bash
127+
# Get assets for specific chain
128+
curl -X GET \
129+
"https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/assets?chain=tbsc" \
130+
-H "Content-Type: application/json" \
131+
-H "Authorization: Bearer ${ACCESS_TOKEN}"
132+
```
133+
134+
Expected Response:
135+
136+
```json
137+
[
138+
{
139+
"id": "08c1271e-b15d-4af8-8929-f75383903da4",
140+
"token": "tfiatusd",
141+
"name": "Testnet US Dollar",
142+
"decimals": 2,
143+
},
144+
{
145+
"id": "bfd0daec-f849-4b96-bdb6-6373bffeb9b6",
146+
"token": "tbsc:usd1",
147+
"name": "Testnet BSC USD1",
148+
"decimals": 18,
149+
"chain": "tbsc",
150+
"backingAsset": "tfiatusd",
151+
"treasuryAccountWalletId": "67c1a025f9999f485f7a71aa26a1da4c"
152+
},
153+
{
154+
"id": "49ff49ea-3355-4717-bbb0-5e8f5cae2202",
155+
"token": "hteth:gousd",
156+
"name": "Testnet goUSD",
157+
"decimals": 6,
158+
"chain": "hteth",
159+
"backingAsset": "tfiatusd",
160+
"treasuryAccountWalletId": "6698e670115059e2efe672436a3aea3b"
161+
}
162+
]
163+
```
164+
165+
### Mint Step 2: Calculate Amount in Base Units
166+
167+
For USD with 2 decimals and amount of 100:
168+
169+
- Base units = 100 × 10² = 10000
170+
171+
```bash
172+
# Calculate programmatically
173+
DECIMALS=2 # From assets API response
174+
AMOUNT_BASE_UNITS=$((${AMOUNT_IN_FULL_UNITS} * 10**${DECIMALS}))
175+
echo "Amount in base units: ${AMOUNT_BASE_UNITS}"
176+
```
177+
178+
### Mint Step 3: Create Mint Order
179+
180+
```bash
181+
curl -X POST \
182+
"https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/order" \
183+
-H "Content-Type: application/json" \
184+
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
185+
-d '{
186+
"sourceWalletId": "'${WALLET_ID}'",
187+
"destinationWalletId": "'${WALLET_ID}'",
188+
"destinationType": "go_account",
189+
"fromAssetId": "usd_asset_id_from_step1",
190+
"toAssetId": "stablecoin_asset_id_from_step1",
191+
"fromAmount": "'${AMOUNT_BASE_UNITS}'",
192+
"type": "mint"
193+
}'
194+
```
195+
196+
Expected Response:
197+
198+
```json
199+
{
200+
"id": "order_id_12345",
201+
"type": "mint",
202+
"status": "pending_funding",
203+
"fromAssetId": "usd_asset_id",
204+
"toAssetId": "stablecoin_asset_id",
205+
"fromAmount": "10000",
206+
"sourceWalletId": "wallet_id",
207+
"destinationWalletId": "wallet_id",
208+
"createdAt": "2025-08-19T10:00:00.000Z"
209+
}
210+
```
211+
212+
### Mint Step 4: Transfer USD to Treasury (via BitGo Express)
213+
214+
```bash
215+
curl -X POST \
216+
"http://${BITGO_EXPRESS_HOST}/api/v2/${OFC_USD_COIN}/wallet/${WALLET_ID}/sendcoins" \
217+
-H "Content-Type: application/json" \
218+
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
219+
-d '{
220+
"address": "'${TREASURY_WALLET_ID}'",
221+
"amount": "'${AMOUNT_BASE_UNITS}'",
222+
"walletPassphrase": "'${WALLET_PASSPHRASE}'",
223+
"sequenceId": "'${ORDER_ID}'"
224+
}'
225+
```
226+
227+
Expected Response:
228+
229+
```json
230+
{
231+
"coin": "ofctusd",
232+
"transfers": [
233+
{
234+
"id": "transfer_id_12345",
235+
"coin": "ofctusd",
236+
"wallet": "source_wallet_id",
237+
"value": -10000,
238+
"baseValue": -10000,
239+
"state": "unconfirmed",
240+
"type": "send"
241+
}
242+
]
243+
}
244+
```
245+
246+
### Mint Step 5: Check Order Status
247+
248+
```bash
249+
curl -X GET \
250+
"https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/orders/${ORDER_ID}" \
251+
-H "Content-Type: application/json" \
252+
-H "Authorization: Bearer ${ACCESS_TOKEN}"
253+
```
254+
255+
Expected Response:
256+
257+
```json
258+
{
259+
"id": "order_id_12345",
260+
"type": "mint",
261+
"status": "completed",
262+
"fromAssetId": "usd_asset_id",
263+
"toAssetId": "stablecoin_asset_id",
264+
"fromAmount": "10000",
265+
"toAmount": "100000000",
266+
"completedAt": "2025-08-19T10:05:00.000Z"
267+
}
268+
```
269+
270+
## Burn Order Process
271+
272+
The burn order process converts stablecoin back to USD:
273+
274+
### Burn Step 1: Get Available Assets
275+
276+
Same as mint process step 1.
277+
278+
### Burn Step 2: Get Treasury Wallet ID
279+
280+
The treasury wallet ID is included in the assets API response from step 1, in the `treasuryAccountWalletId` field of the stablecoin asset.
281+
282+
### Burn Step 3: Calculate Amount in Base Units
283+
284+
For stablecoin with 6 decimals and amount of 100:
285+
286+
- Base units = 100 × 10⁶ = 100000000
287+
288+
```bash
289+
# Calculate programmatically
290+
DECIMALS=6 # From assets API response for stablecoin
291+
AMOUNT_BASE_UNITS=$((${AMOUNT_IN_FULL_UNITS} * 10**${DECIMALS}))
292+
echo "Amount in base units: ${AMOUNT_BASE_UNITS}"
293+
```
294+
295+
### Burn Step 4: Create Burn Order
296+
297+
```bash
298+
curl -X POST \
299+
"https://app.bitgo-${BITGO_ENV}.com/api/stablecoin/v1/enterprise/${ENTERPRISE_ID}/order" \
300+
-H "Content-Type: application/json" \
301+
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
302+
-d '{
303+
"sourceWalletId": "'${WALLET_ID}'",
304+
"destinationWalletId": "'${WALLET_ID}'",
305+
"destinationType": "go_account",
306+
"fromAssetId": "stablecoin_asset_id_from_step1",
307+
"toAssetId": "usd_asset_id_from_step1",
308+
"fromAmount": "'${AMOUNT_BASE_UNITS}'",
309+
"type": "burn"
310+
}'
311+
```
312+
313+
### Burn Step 5: Transfer Stablecoin to Treasury (via BitGo Express)
314+
315+
```bash
316+
curl -X POST \
317+
"http://${BITGO_EXPRESS_HOST}/api/v2/${OFC_STABLECOIN}/wallet/${WALLET_ID}/sendcoins" \
318+
-H "Content-Type: application/json" \
319+
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
320+
-d '{
321+
"address": "'${TREASURY_WALLET_ID}'",
322+
"amount": "'${AMOUNT_BASE_UNITS}'",
323+
"walletPassphrase": "'${WALLET_PASSPHRASE}'",
324+
"sequenceId": "'${ORDER_ID}'"
325+
}'
326+
```
327+
328+
### Burn Step 6: Check Order Status
329+
330+
Same as mint process step 5.
331+
332+
## GoAccount Transfers via BitGo Express
333+
334+
### Prerequisites for GoAccount Transfers
335+
336+
1. **BitGo Express Setup**: BitGo Express must be running locally
337+
2. **OFC Asset**: Use the "ofc" prefixed version of your asset (e.g., `ofctusd` for USD transfers)
338+
3. **Address Parameter**: For treasury transfers and most GoAccount operations, use `address` parameter with the destination wallet ID
339+
340+
### Transfer Parameters
341+
342+
| Parameter | Description | Required |
343+
|-----------|-------------|----------|
344+
| `address` | Destination wallet ID or external address | Yes |
345+
| `walletId` | Alternative to address for GoAccount transfers (context-dependent) | No |
346+
| `amount` | Amount in base units | Yes |
347+
| `walletPassphrase` | Source wallet passphrase | Yes |
348+
| `sequenceId` | Unique identifier (use order ID) | Yes |
349+
350+
351+
## API Endpoints Reference
352+
353+
### Stablecoin API Endpoints
354+
355+
| Method | Endpoint | Description |
356+
|--------|----------|-------------|
357+
| GET | `/api/stablecoin/v1/assets` | List available assets (includes treasury wallet IDs) |
358+
| POST | `/api/stablecoin/v1/enterprise/{enterpriseId}/order` | Create order |
359+
| GET | `/api/stablecoin/v1/enterprise/{enterpriseId}/orders/{orderId}` | Get order details |
360+
361+
### BitGo Express Endpoints
362+
363+
| Method | Endpoint | Description |
364+
|--------|----------|-------------|
365+
| GET | `/api/v2/ping` | Health check |
366+
| POST | `/api/v2/{coin}/wallet/{walletId}/sendmany` | Send to multiple recipients |
367+
368+
### Base URLs
369+
370+
- **Testnet**: `https://app.bitgo-test.com`
371+
- **Production**: `https://app.bitgo.com`
372+
- **BitGo Express**: `http://localhost:3080` (default)
373+
374+
## Security Considerations
375+
376+
1. **API Keys**: Store access tokens securely, never commit to version control
377+
2. **Wallet Passphrases**: Use environment variables, avoid hardcoding
378+
3. **Network Security**: Use HTTPS for all API calls
379+
380+
## Troubleshooting
381+
382+
### Common Issues
383+
384+
1. **BitGo Express Not Running**: Ensure Express server is started and accessible
385+
2. **Invalid Asset IDs**: Verify asset IDs from the assets API response
386+
3. **Insufficient Balance**: Check wallet balance before initiating transfers
387+
4. **Wrong Environment**: Ensure consistent use of test/prod environments
388+
5. **Sequence ID Conflicts**: Use unique sequence IDs for each transaction
389+
390+
### Debug Commands
391+
392+
```bash
393+
# Check BitGo Express status
394+
curl -X GET http://localhost:3080/api/v2/ping
395+
```
396+
397+
---
398+
399+
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.

0 commit comments

Comments
 (0)