Back to the application

Deploy and Mint a Bond via API

Step-by-step guide for creating and minting bond tokens using the ATK REST API

PREREQUISITES

Before running these commands:

  1. Platform URL - Know your ATK platform URL (e.g., https://your-platform.example.com)
  2. Have ATK deployed - Running instance (local or hosted)
  3. Account setup - User account with email/password and PINCODE enabled
  4. Admin role - Required to grant tokenManager system role (Step 3)
  5. Create a stablecoin - Complete the Stablecoin Guide first, as bonds require a denomination asset

You'll need:

  • Your wallet address (from Step 2)
  • A deployed stablecoin contract address (denomination asset)

Quick reference

StepWhatEndpoint
1Sign inPOST /api/auth/sign-in/email
2Get user infoGET /api/user/me
3Grant system rolesSee Set Up Roles guide
4Create bondPOST /api/token/create (type: "bond")
5Grant token rolesSee Set Up Roles guide
6UnpausePOST /api/token/{contract}/unpause
7Mint bondsPOST /api/token/{contract}/mint
8VerifyGET /api/token/{contract}/holders

STEP-BY-STEP COMMANDS

Step 1: sign in

curl -v -X POST YOUR_PLATFORM_URL/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
  }'

Expected: Status 200 OK, session cookie saved to cookies.txt

Step 2: get your wallet address

curl -s YOUR_PLATFORM_URL/api/user/me \
  -b cookies.txt | jq '.'

Expected: JSON with your user info including wallet address

Save your wallet address - you'll need it!

Step 3: grant system roles

REQUIRED: You need the tokenManager system role to create tokens.

Follow the Set Up Roles guide to grant yourself the tokenManager role (Step 2 in that guide).

Note: Only users with admin role can grant system roles. If you don't have admin access, ask your system administrator to grant you the tokenManager role.

Step 4: create bond token

curl -v -X POST YOUR_PLATFORM_URL/api/token/create \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "type": "bond",
    "name": "Test Corporate Bond",
    "symbol": "TCBD",
    "decimals": 18,
    "countryCode": "840",
    "cap": "1000000000000000000000000",
    "faceValue": "1000000000000000000000",
    "maturityDate": "2026-12-31T23:59:59Z",
    "denominationAsset": "YOUR_STABLECOIN_CONTRACT_ADDRESS",
    "initialModulePairs": [],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

Parameters:

  • type: Must be "bond"
  • name: Bond name (e.g., "Test Corporate Bond")
  • symbol: Bond symbol (e.g., "TCBD")
  • decimals: Usually 18 for bonds
  • countryCode: ISO country code (840 = USA, 056 = Belgium, 276 = Germany)
  • cap: Maximum supply (e.g., "1000000000000000000000000" = 1M bonds with 18 decimals)
  • faceValue: Redemption value per bond (e.g., "1000000000000000000000" = 1000 tokens with 18 decimals)
  • maturityDate: When the bond matures (ISO 8601 format)
  • denominationAsset: Your stablecoin contract address from the stablecoin guide
  • initialModulePairs: Compliance modules (empty array [] for basic setup)

Expected: Status 200 OK, returns bond data with id (contract address)

SAVE THE CONTRACT ADDRESS from the response!

Step 5: grant token roles

REQUIRED: Grant yourself supplyManagement (for minting) and emergency (for unpausing) roles on the bond contract.

Follow the Set Up Roles guide Step 4 to grant these roles. Use your bond contract address from Step 4.

Step 6: unpause the bond

New tokens start paused. Unpause to enable transfers:

curl -v -X POST YOUR_PLATFORM_URL/api/token/YOUR_BOND_CONTRACT_ADDRESS/unpause \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "contract": "YOUR_BOND_CONTRACT_ADDRESS",
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

Replace:

  • YOUR_BOND_CONTRACT_ADDRESS: The bond contract from Step 4

Expected: Status 200 OK

Note: This step requires the emergency role from Step 5.

Step 7: mint bonds

curl -v -X POST YOUR_PLATFORM_URL/api/token/YOUR_BOND_CONTRACT_ADDRESS/mint \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "contract": "YOUR_BOND_CONTRACT_ADDRESS",
    "recipients": ["YOUR_RECIPIENT_WALLET"],
    "amounts": ["100000000000000000000"],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

Parameters:

  • contract: Your bond contract address
  • recipients: Array of recipient wallet address(es)
  • amounts: Array of amounts in smallest unit
    • To mint X bonds with 18 decimals, use: X * 10^18
    • Example: 100 * 10^18 = 100 bonds
    • Example: 1 * 10^18 = 1 bond

Expected: Status 200 OK, returns token data with updated totalSupply

Note: This step requires the supplyManagement role from Step 5.

Step 8: verify the mint

curl -s YOUR_PLATFORM_URL/api/token/YOUR_BOND_CONTRACT_ADDRESS/holders?tokenAddress=YOUR_BOND_CONTRACT_ADDRESS \
  -b cookies.txt | jq '.'

Expected: Shows bond holders with their balances

FULL SCRIPT

Replace the variables and run:

#!/bin/bash

# ============================================
# YOUR VALUES (CONFIGURE THESE)
# ============================================
EMAIL="YOUR_EMAIL"
PASSWORD="YOUR_PASSWORD"
PINCODE="YOUR_PINCODE"
RECIPIENT="YOUR_WALLET_ADDRESS"  # From Step 2
STABLECOIN_CONTRACT="YOUR_STABLECOIN_CONTRACT"  # From stablecoin guide
BASE_URL="YOUR_PLATFORM_URL"

# ============================================
# COMMANDS (DO NOT EDIT BELOW)
# ============================================

echo "Step 1: Signing in..."
curl -s -X POST $BASE_URL/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}" > /dev/null

echo " Signed in"
echo ""

echo "Step 2: Getting user info..."
USER_INFO=$(curl -s $BASE_URL/api/user/me -b cookies.txt)
WALLET=$(echo $USER_INFO | jq -r '.wallet')
echo " Your wallet: $WALLET"
echo ""

echo "Step 3: Grant system roles..."
echo " Follow the Set Up Roles guide to grant yourself the tokenManager role"
echo " See: /developer-guides/api-integration/set-up-roles"
echo ""

echo "Step 4: Creating bond token..."
# Calculate maturity date (1 year from now)
MATURITY=$(date -u -v+1y +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "+1 year" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "2026-12-31T23:59:59Z")

CREATE_RESPONSE=$(curl -s -X POST $BASE_URL/api/token/create \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d "{\"type\":\"bond\",\"name\":\"Test Corporate Bond\",\"symbol\":\"TCBD\",\"decimals\":18,\"countryCode\":\"840\",\"cap\":\"1000000000000000000000000\",\"faceValue\":\"1000000000000000000000\",\"maturityDate\":\"$MATURITY\",\"denominationAsset\":\"$STABLECOIN_CONTRACT\",\"initialModulePairs\":[],\"walletVerification\":{\"secretVerificationCode\":\"$PINCODE\",\"verificationType\":\"PINCODE\"}}")

BOND_CONTRACT=$(echo $CREATE_RESPONSE | jq -r '.id')
echo " Bond created: $BOND_CONTRACT"
echo ""

echo "Step 5: Grant token roles..."
echo " Follow the Set Up Roles guide Step 4 to grant supplyManagement and emergency roles"
echo " See: /developer-guides/api-integration/set-up-roles"
echo ""

echo "Step 6: Unpausing bond..."
curl -s -X POST $BASE_URL/api/token/$BOND_CONTRACT/unpause \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d "{\"contract\":\"$BOND_CONTRACT\",\"walletVerification\":{\"secretVerificationCode\":\"$PINCODE\",\"verificationType\":\"PINCODE\"}}" > /dev/null
echo " Bond unpaused"
echo ""

echo "Step 7: Minting 100 bonds..."
MINT_RESPONSE=$(curl -s -X POST $BASE_URL/api/token/$BOND_CONTRACT/mint \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d "{\"contract\":\"$BOND_CONTRACT\",\"recipients\":[\"$RECIPIENT\"],\"amounts\":[\"100000000000000000000\"],\"walletVerification\":{\"secretVerificationCode\":\"$PINCODE\",\"verificationType\":\"PINCODE\"}}")

echo " Minted!"
echo ""
echo "Response:"
echo $MINT_RESPONSE | jq '.'
echo ""

echo "Step 8: Checking holders..."
curl -s $BASE_URL/api/token/$BOND_CONTRACT/holders?tokenAddress=$BOND_CONTRACT -b cookies.txt | jq '.token.balances'

echo ""
echo "DONE! Bond minted successfully!"
echo "Contract: $BOND_CONTRACT"

Amount calculations

For bonds with 18 decimals, use the formula: amount * 10^18

Examples:

  • 1 bond = 1 * 10^18 = 1000000000000000000
  • 10 bonds = 10 * 10^18 = 10000000000000000000
  • 100 bonds = 100 * 10^18 = 100000000000000000000
  • 1000 bonds = 1000 * 10^18 = 1000000000000000000000

To mint X bonds, calculate: X * 10^decimals (where decimals = 18 for bonds)

Troubleshooting

"Authentication missing" → Run Step 1 again (sign in)

"PINCODE_INVALID" → Check your PINCODE in account settings

"USER_NOT_AUTHORIZED" / "tokenManager required" → Follow the Set Up Roles guide Step 2 to grant the tokenManager role (requires admin access)

"Permission denied" → Follow the Set Up Roles guide Step 4 to grant token roles

"Token is paused" → Make sure Step 6 (unpause) succeeded and you have emergency role

"Invalid denomination asset" → Verify your stablecoin contract address from the stablecoin guide

"Maturity date must be in the future" → Use a future date in ISO 8601 format (e.g., "2026-12-31T23:59:59Z")

Need jq? Install with: brew install jq (Mac) or apt install jq (Linux)

API reference
Deploy and Mint a Deposit Token via API