Documentation

Fungible Tokens

Tokenization Engine Integration Guide - Fungible Tokens

Suggest Edits

This guide covers the integration of fungible tokens representing 1:1 fiat-backed stablecoins using zerohash's tokenization engine.

Token Characteristics

Fungible Stablecoin Tokens

  • Standard Compliance: ERC-1155/ERC-20 compatible with 6 decimal precision
  • 1:1 Fiat Backing: Full collateralization with fiat reserves
  • Multiple Minting: Supports multiple mint operations with configurable amounts
  • Token Identification: Uses token ID 0 for all fungible token operations
  • Network Support: Available across 10+ EVM networks

Token symbols include network specification (e.g., "USDFI.ETH" for Ethereum L1). All examples use Ethereum Sepolia testnet for demonstration purposes.

Core Operations

1. Token Minting

Mint stablecoin tokens after fiat collateral is locked in reserve accounts.

Endpoint: POST /v1/token/mint

Request Parameters:

{ 
    "amount": "1.56",
    "token_symbol": "USDFI.ETH",
    "client_request_id": "22b6cbea-1c77-415f-b866-2987b0b869ab",
    "participant_code": "SB5LRL",
    "receiver": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E"
}

Response:

{ 
    "token_request_id": "22b6cbea-1c77-415f-b866-2987b0b869ab"
}

Field Descriptions:

  • amount: Token amount to mint (string, supports up to 6 decimal places)
  • token_symbol: Token identifier with network suffix
  • client_request_id: Unique identifier for idempotency (UUID format recommended)
  • participant_code: Platform-specific participant identifier
  • receiver: Destination wallet address (treasury or external wallet)

2. Token Burning

Burn stablecoin tokens to initiate fiat settlement to token holders.

Endpoint: POST /v1/token/burn

Request Parameters:

{ 
    "amount": "0.56",
    "token_symbol": "USDFI.ETH",
    "client_request_id": "33b6cbea-1c77-415f-b866-2987b0b869cc",
    "participant_code": "SB5LRL",
    "owner": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E"
}

Response:

{ 
    "token_request_id": "33b6cbea-1c77-415f-b866-2987b0b869cc"
}

Field Descriptions:

  • owner: Address that owns the tokens to be burned
  • Other fields same as mint operation

Example transaction

3. Batch Token Transfer

Transfer tokens from treasury wallet to multiple customer addresses in a single operation.

Endpoint: POST /v1/token/transfer

Request Parameters:

{ 
    "token_symbol": "USDFI.ETH",
    "client_request_id": "44b6cbea-1c77-415f-b866-2987b0b869dd",
    "participant_code": "SB5LRL",
    "sender": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E",
    "transfers": [
        {"receiver": "0x742d35Cc6634C0532925a3b8D", "amount": "500.00"},
        {"receiver": "0x8ba1f109551bD432803012645Hj", "amount": "1000.00"},
        {"receiver": "0x2546BcD3c84621e976D8185a4F", "amount": "7500.00"}
    ]
}

Response:

{ 
    "token_request_id": "44b6cbea-1c77-415f-b866-2987b0b869dd"
}

4. Operation Status Monitoring

Get real-time status updates for all tokenization operations.

Endpoint: GET /token/{token_request_id}

Example: POST /token/22b6cbea-1c77-415f-b866-2987b0b869ab

Response:

{ 
    "message": {
        "token_request_id": "22b6cbea-1c77-415f-b866-2987b0b869ab",
        "token_symbol": "USDFI.ETH",
        "token_id": "",
        "action": "MINT",
        "owner": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E",
        "amount": "1.56",
        "platform_code": "NAXJ2C",
        "participant_code": "SB5LRL",
        "status": "COMPLETED",
        "tx_hash": "0x8ab7bedd266aee63b5493be7b06aefa1ae4df11ade278c95a13adc1854663558",
        "network_fee": "0.000099"
    }
}

Status Values:

  • PENDING: Operation initiated, awaiting processing
  • PROCESSING: Transaction submitted to blockchain
  • COMPLETED: Transaction confirmed on-chain
  • FAILED: Operation failed (see error details)

5. Treasury Wallet Balance

Query the current balance of the treasury wallet for a specific token.

Endpoint: GET /v1/token/treasury-balance/{token_symbol}

Example: POST /v1/token/treasury-balance/USDFI.ETH

Response:

{ 
    "token_symbol": "USDFI.ETH",
    "wallet_address": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E",
    "token_account": "1D...ATA",
    "balance": "750000000",
    "decimals": 6,
    "as_of": "2025-01-01T12:30:00Z"
}

Field Descriptions:

  • token_account: Solana-specific field (when applicable)
  • balance: Raw balance amount (multiply by 10^decimals for actual value)
  • as_of: Timestamp of balance snapshot

Emergency and Compliance Operations

Emergency Pause / Unpause

Temporarily halt all token operations for emergency situations.

Pause Endpoint: POST /v1/contract/pause

Unpause Endpoint: POST /v1/contract/unpause

Request Parameters:

{ 
    "token_symbol": "USDFI.ETH",
    "client_request_id": "55b6cbea-1c77-415f-b866-2987b0b869ee",
    "reason": "incident-IR-2025-0815",
    "memo": "halt while rotating signer keys"
}

Response:

{ 
    "token_request_id": "55b6cbea-1c77-415f-b866-2987b0b869ee"
}

Field Descriptions:

  • reason: Optional incident reference code
  • memo: Optional human-readable description]

Lawful Order Enforcement

Compliance tools for regulatory requirements and court orders.

Freeze Account: POST /v1/token/lawful/freeze

Unfreeze Account: POST /v1/token/lawful/unfreeze

Force Burn (Wipe): POST /v1/token/lawful/wipe

Request Parameters:

{ 
    "token_symbol": "USDFI.ETH",
    "client_request_id": "66b6cbea-1c77-415f-b866-2987b0b869ff",
    "subject": "0x742d35Cc6634C0532925a3b8D",
    "order_ref": {
        "authority": "Court of X",
        "doc_uri": "https://.../order.pdf",
        "case_id": "CASE-2025-0123"
    },
    "memo": "OFAC/LE request #0123"
}

Response:

{ 
    "token_request_id": "66b6cbea-1c77-415f-b866-2987b0b869ff"
}

Field Descriptions:

  • subject: Target user account address
  • order_ref: Legal authority and documentation references
  • memo: Optional compliance reference

Economics and Yield

Commission Structure

A smart contract commission mechanism automatically deducts a percentage of fungible token transfers to a designated address.

Commission Features:

  • Tax Rate: Defined in basis points (BPS), maximum 5000 BPS (50%)
  • Fungible Only: Only transfers of fungible tokens (token_id == 0) are subject to commission
  • Automatic Deduction: Commission automatically sent to configured tax address

Transfer Example with Commission:

  • Original transfer: 200,000 USDFI
  • Commission (25 BPS): 500 USDFI to tax address
  • Net transfer: 199,500 USDFI to recipient
  • Example transaction

Yield Distribution

Stablecoin yield can be distributed by minting tokens directly to holder addresses, simulating interest payments from reserve account earnings.

Yield Implementation:

{ 
    "amount": "15.75",
    "token_symbol": "USDFI.ETH",
    "client_request_id": "yield-2025-01-15-user123",
    "participant_code": "SB5LRL",
    "receiver": "0x742d35Cc6634C0532925a3b8D"
}

Multi-Signature Support

For enhanced security, treasury operations can require multi-signature authorization using customer-hosted co-signers.

Signature Request Webhook

When multi-signature is enabled, you'll receive webhooks for signing requests.

Webhook URL: https://<webhook-handler-url>/webhooks/token/signature-request

Webhook Headers:

x-zh-hook-notification-id: <unique-webhook-id>
x-zh-hook-payload-type: token_signature_request
x-zh-hook-timestamp: <unix-timestamp>
x-zh-hook-signature: <hmac-sha256-signature>

Signature Verification:

to_hex(hmac(sha256(payload + timestamp), your-secret))

Webhook Payload:

{ 
    "operation": {
        "type": "mint",
        "token_request_id": "22b6cbea-1c77-415f-b866-2987b0b869ab",
        "token_symbol": "USDFI.ETH",
        "to": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E",
        "amount": "1000.00",
        "memo": "Monthly treasury distribution"
    },
    "signing": {
        "signer_address": "0x45D9A0Ee3a917Eccd6182C030dC9f18897eCf79E",
        "deadline": "2025-01-01T12:30:00Z",
        "message": "0x1234567890abcdef...",
        "scheme": "EVM_EIP712"
    }
}

Operation Types:

  • mint | burn | pause | unpause | freeze | wipe | transfer

Signing Schemes:

  • EVM_EIP712: Ethereum EIP-712 structured data signing
  • SOL_ED25519: Solana Ed25519 signature scheme

Signature Callback

Submit signatures back to complete multi-sig operations.

Endpoint: POST /v1/token/signatures/<webhook-id>

Request Parameters:

{ 
    "scheme": "EVM_EIP712",
    "pubkey": "0x04a1b2c3d4...",
    "signature": "0x1234567890abcdef...",
    "signed_at": "2025-01-01T12:29:45Z"
}

Response:

{ 
    "webhook_id": "unique-webhook-id",
    "status": "verified"
}

Response Status Values:

  • verified: Signature verified and accepted
  • rejected: Signature verification failed

Important Notes:

  • All webhooks must receive HTTP 2xx response to acknowledge receipt
  • Unacknowledged webhooks will be re-sent
  • Complete signature callback before the deadline specified in webhook
  • Use compressed format for public keys

Updated 1 day ago