smom-dbis-138/docs/tokenization/API_DOCUMENTATION.md

Tokenization API Documentation

Overview

The Tokenization API provides endpoints for minting, transferring, and redeeming tokenized assets, with integration across SolaceNet, Sub-Volumes, and microservices.

Base URL

https://api.tokenization.chain138.example.com

Authentication

All endpoints require SolaceNet capability checks and may require Indy credentials.

Authorization: Bearer <api_key>
X-Tenant-Id: <tenant_id>
X-Program-Id: <program_id>
X-Region: <region>
X-Channel: <channel>

SolaceNet Tokenization Endpoints

1. Mint Tokenized Asset

Mint a new tokenized asset (requires tokenization.mint capability).

Endpoint: POST /api/v1/solacenet/tokenization/mint

Request Body:

{
  "underlyingAsset": "EUR",
  "amount": "1000000.00",
  "issuer": "0x...",
  "reserveId": "RESERVE-EUR-001",
  "recipient": "0x...",
  "regulatoryFlags": {
    "kyc": true,
    "aml": true,
    "regulatoryApproval": true
  }
}

Response:

{
  "requestId": "TOKEN-1234567890-abc123",
  "fabricTokenId": "EUR-T-2025-001",
  "fabricTxHash": "0x...",
  "besuTokenAddress": "0x...",
  "besuTxHash": "0x...",
  "status": "COMPLETED"
}

2. Transfer Tokenized Asset

Transfer tokenized asset (requires tokenization.transfer capability).

Endpoint: POST /api/v1/solacenet/tokenization/transfer

Request Body:

{
  "tokenId": "EUR-T-2025-001",
  "from": "0x...",
  "to": "0x...",
  "amount": "100.00"
}

Response:

{
  "txHash": "0x...",
  "status": "completed"
}

3. Redeem Tokenized Asset

Redeem tokenized asset back to underlying asset (requires tokenization.redeem capability).

Endpoint: POST /api/v1/solacenet/tokenization/redeem

Request Body:

{
  "tokenId": "EUR-T-2025-001",
  "redeemer": "0x...",
  "amount": "100.00"
}

Response:

{
  "fabricTxHash": "0x...",
  "besuTxHash": "0x...",
  "status": "completed"
}

4. Get Tokenization Status

Get status of tokenization request (requires tokenization.view capability).

Endpoint: GET /api/v1/solacenet/tokenization/status/:requestId

Response:

{
  "requestId": "TOKEN-1234567890-abc123",
  "status": "BESU_MINTED",
  "fabricTokenId": "EUR-T-2025-001",
  "fabricTxHash": "0x...",
  "besuTokenAddress": "0x...",
  "besuTxHash": "0x...",
  "settlementFile": {
    "blockchain": {...},
    "traditional": {...}
  }
}

5. Get Token Details

Get details of a tokenized asset (requires tokenization.view capability).

Endpoint: GET /api/v1/solacenet/tokenization/token/:tokenId

Response:

{
  "tokenId": "EUR-T-2025-001",
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "totalSupply": "1000000.00",
  "backedAmount": "1000000.00",
  "backingRatio": 1.0,
  "status": "ACTIVE",
  "reserveStatus": {
    "reserveId": "RESERVE-EUR-001",
    "totalReserve": "1000000.00",
    "availableReserve": "0.00",
    "lastAttested": 1234567890
  }
}

FireFly Tokenization Endpoints

6. Initiate Minting Workflow

Endpoint: POST /api/tokenization/mint

Request Body:

{
  "requestId": "TOKEN-1234567890-abc123",
  "underlyingAsset": "EUR",
  "amount": "1000000.00",
  "issuer": "0x...",
  "reserveId": "RESERVE-EUR-001"
}

7. Get Settlement File

Endpoint: GET /api/tokenization/settlement/:txHash

Response:

{
  "blockchain": {
    "hash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "value": "1000000000000000000",
    "gas": "21000",
    "gasPrice": "20000000000",
    "nonce": "0",
    "blockNumber": "12345",
    "transactionIndex": "0",
    "input": "0x...",
    "chainId": "138",
    "usdtErc20": "token"
  },
  "traditional": {
    "swiftReference": "SWIFT-1234567890-ABC",
    "target2Code": "T2-1234567890",
    "regulatoryFlags": {...},
    "identityCode": "42Q GB DD GB 42FOP 36F",
    "permitCode": "PERMIT-1234567890",
    "accessCode": "ACCESS-1234567890"
  }
}

Sub-Volume Integration Endpoints

8. GAS Settlement for Tokenized Asset

Endpoint: POST /api/gas/tokenization/settle

Request Body:

{
  "tokenAddress": "0x...",
  "fabricTokenId": "EUR-T-2025-001",
  "sourceBankId": "BANK-001",
  "destinationBankId": "BANK-002",
  "amount": "100.00",
  "currencyCode": "EUR"
}

9. GRU Valuation for Tokenized Asset

Endpoint: POST /api/gru/tokenization/value

Request Body:

{
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "amount": "100.00",
  "targetCurrency": "GRU"
}

Response:

{
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "amount": "100.00",
  "gruValue": "95.50",
  "gruUnit": "M00",
  "xauRate": "2000.00",
  "triangulationRate": "0.955"
}

10. Metaverse Virtual Representation

Endpoint: POST /api/metaverse/tokenization/create-virtual

Request Body:

{
  "tokenAddress": "0x...",
  "fabricTokenId": "EUR-T-2025-001",
  "metaverseNodeId": "METAVERSE-DUBAI",
  "virtualAssetId": "VIRTUAL-LAND-001",
  "amount": "100.00",
  "currencyCode": "EUR"
}

Error Responses

All endpoints may return error responses:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Codes

• CAPABILITY_NOT_GRANTED: SolaceNet capability not granted
• CREDENTIAL_INVALID: Indy credential invalid or missing
• RESERVE_INSUFFICIENT: Insufficient reserve for operation
• TOKEN_NOT_FOUND: Tokenized asset not found
• INVALID_STATUS: Invalid operation status
• POLICY_DENIED: Policy engine denied operation
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions

Rate Limiting

• Mint/Transfer/Redeem: 100 requests per minute per tenant
• View operations: 1000 requests per minute per tenant

WebSocket Events

Real-time tokenization status updates:

Connection: wss://api.tokenization.chain138.example.com/ws

Subscribe:

{
  "action": "subscribe",
  "requestId": "TOKEN-1234567890-abc123"
}

Event:

{
  "event": "tokenization_status_update",
  "requestId": "TOKEN-1234567890-abc123",
  "status": "BESU_MINTING",
  "timestamp": 1234567890
}