Skip to main content

🧵 Configure Bond on ERC3643 Token

Welcome to the complete guide for configuring bond parameters on an ERC3643 token using the Token City Blockchain API.

🌟 Objective: Set up and manage bond configurations for tokenized securities, including interest payments, fees, and tax collection parameters.

📚 OpenAPI Documentation​

✨ Workflow Summary​

This workflow guides you through configuring and managing bonds for ERC3643 tokens:

  1. 🔹 Configure bond parameters (interest rate, fees, tax, payment wallet).
  2. 🔹 Monitor transaction confirmation via webhook.
  3. 🔹 Retrieve bond configuration to verify settings.
  4. 🔹 Query earned interest for specific holders.

📋 Workflow Steps Table​

StepAPI OperationMethodParametersOutputsDescription
Configure bond parametersPOST /v2/erc3643/{tokenId}/bondPOSTBond Configuration DataTransaction ID (txUUID)Sets up bond parameters including interest, fees, and payment wallets
Monitor transaction statusWebhook subscription--TX_MINED or TX_FAILEDReceives confirmation when bond configuration is mined on blockchain
Retrieve bond configurationGET /v2/erc3643/{tokenId}/bondGETtokenIdBond configuration detailsRetrieves current bond parameters for verification
Query holder earned interestGET /v2/erc3643/{tokenId}/bond/{holder}/earned-interestGETtokenId, holder addressEarned interest amountCalculates accumulated interest for a specific token holder

🎨 Workflow Visualizations​

🌊 Mermaid Sequence Diagram​

📝 Step-by-Step Implementation​

Step 1: Configure Bond Parameters​

Set up the bond configuration for your ERC3643 token.

Endpoint: POST /v2/erc3643/{tokenId}/bond

Request Body:

{
  "nominalValue": "1000",
  "fee": "15",
  "tax": "1",
  "feeCollector": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "taxCollector": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "anualInterest": "5",
  "finishDate": "2025-11-06T12:02:51+0000",
  "interestPayingWallet": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343"
}

Request Parameters:

  • nominalValue: Face value of each bond token
  • fee: Fee percentage charged on generated interests (e.g., "15" = 15%)
  • tax: Tax percentage applied to interest payments (e.g., "1" = 1%)
  • feeCollector: Ethereum address that receives transaction fees
  • taxCollector: Ethereum address that receives tax payments
  • anualInterest: Annual interest rate percentage (e.g., "5" = 5% APY)
  • finishDate: Bond maturity date in ISO 8601 format
  • interestPayingWallet: Ethereum address that funds interest payments

Response:

{
  "id": "567e7895-c76b-12d3-a456-426614174000"
}

The response includes a transaction UUID (id) that you can use to track the configuration transaction status.

Step 2: Monitor Transaction Confirmation​

Subscribe to webhooks to receive bond configuration status updates.

Webhook Events:

  • TX_MINED: Bond configuration successfully applied on blockchain
  • TX_FAILED: Configuration transaction failed

TX_MINED Webhook:

{
  "type": "TX_MINED",
  "event": {
    "txUUID": "567e7895-c76b-12d3-a456-426614174000",
    "txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "blockNumber": 12345678,
    "timestamp": 1634567890
  }
}

TX_FAILED Webhook:

{
  "type": "TX_FAILED",
  "event": {
    "txUUID": "567e7895-c76b-12d3-a456-426614174000",
    "reason": "Insufficient permissions",
    "timestamp": 1634567890
  }
}

Step 3: Retrieve Bond Configuration​

Verify the bond configuration settings.

Endpoint: GET /v2/erc3643/{tokenId}/bond

Path Parameters:

  • tokenId: The UUID of the ERC3643 token (e.g., 123e4567-e89b-12d3-a456-426614174000)

Response:

{
  "nominalValue": "1000",
  "fee": "15",
  "tax": "1",
  "feeCollector": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "taxCollector": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "anualInterest": "5",
  "finishDate": "2025-11-06T12:02:51+0000",
  "interestPayingWallet": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343"
}

This endpoint returns the current bond configuration, allowing you to verify all parameters were set correctly.

Step 4: Query Earned Interest for Holders​

Calculate the accumulated interest for a specific token holder.

Endpoint: GET /v2/erc3643/{tokenId}/bond/{holder}/earned-interest

Path Parameters:

  • tokenId: The UUID of the ERC3643 token (e.g., 123e4567-e89b-12d3-a456-426614174000)
  • holder: The Ethereum address of the token holder (e.g., 0xabc1234567890defABC1234567890DEFabc12345)

Response:

{
  "earnedAmount": "1000.52"
}

The earnedAmount represents the total interest earned by the holder based on:

  • Their token balance
  • The annual interest rate
  • The time elapsed since their last token acquisition

💡 Key Concepts​

What is a Bond Token?​

A bond token is a tokenized debt security that:

  • Represents a loan from the investor to the issuer
  • Pays periodic interest to token holders
  • Has a defined maturity date
  • Can be traded on secondary markets (if transferable)

Bond Parameters Explained​

  1. Nominal Value: The face value of each token, used to calculate interest payments
  2. Annual Interest: The yearly interest rate (APY) paid to token holders
  3. Fee: Transaction fee percentage collected by the fee collector
  4. Tax: Tax percentage applied to interest payments
  5. Finish Date: Bond maturity date when principal is returned
  6. Interest Paying Wallet: Must be funded to pay interest to holders
  7. Fee/Tax Collectors: Addresses that receive fees and taxes

⚠️ Important Notes​

  1. Admin Permissions: Only token administrators (issuer/operator) can configure bond parameters
  2. Interest Paying Wallet: Must be funded with sufficient tokens/currency to pay interest
  3. Fee and Tax Collectors: Should be valid Ethereum addresses; can be the same address
  4. Finish Date: Must be in the future; use ISO 8601 format with timezone
  5. Percentage Values: Use string format for precise decimal handling (e.g., "5" for 5%)
  6. One-Time Configuration: Bond parameters may be immutable once set (check token implementation)
  7. Webhook Subscription: Set up webhook subscriptions before configuring bond to receive status updates

🔗 Related Endpoints​

🆘 Troubleshooting​

Configuration Transaction Failed​

If bond configuration fails, verify:

  • ✓ You have administrator permissions on the token contract
  • ✓ All wallet addresses are valid Ethereum addresses (checksummed)
  • ✓ Interest rate, fee, and tax percentages are within acceptable ranges
  • ✓ Finish date is in the future and properly formatted
  • ✓ Token contract supports bond functionality
  • ✓ Sufficient gas is available for the transaction

Interest Calculation Shows Zero​

If earned interest is zero, check:

  • ✓ Bond configuration is active (check Step 3)
  • ✓ Holder has a non-zero token balance
  • ✓ Sufficient time has elapsed since token acquisition
  • ✓ Annual interest rate is greater than zero

Interest Payment Failed​

If interest payments fail:

  • ✓ Interest paying wallet is funded with sufficient balance
  • ✓ Interest paying wallet has necessary approvals
  • ✓ Tax and fee collector addresses are valid

📚 Additional Resources​

💼 Use Case Example​

Corporate Bond Issuance​

A company issues a 5-year corporate bond token:

{
  "nominalValue": "10000",
  "anualInterest": "4.5",
  "fee": "0.5",
  "tax": "15",
  "finishDate": "2030-01-01T00:00:00+0000",
  "feeCollector": "0xCompanyTreasuryAddress",
  "taxCollector": "0xTaxAuthorityAddress",
  "interestPayingWallet": "0xCompanyReserveAddress"
}