API Documentation

Version 1.0 | RESTful API

Base URL: https://your-project.vercel.app/api
Local Development: http://localhost:3000/api

🔗 Blockchain Endpoints

GET /blockchain

Retrieve the entire blockchain with all blocks and transactions.

Response:

{
  "chain": [
    {
      "index": 0,
      "timestamp": 1761687000000,
      "transactions": [],
      "previousHash": "0",
      "hash": "000abc...",
      "nonce": 262,
      "merkleRoot": "..."
    }
  ],
  "length": 1,
  "isValid": true
}

GET /block/:index

Get a specific block by its index number.

Parameters:

index (number, required) - Block index

Example Request:

GET /api/block/0

Response:

{
  "index": 0,
  "timestamp": 1761687000000,
  "transactions": [],
  "previousHash": "0",
  "hash": "000abc123...",
  "nonce": 262,
  "merkleRoot": ""
}

GET /block/latest

Get the most recent block in the chain.

GET /stats

Get blockchain statistics and metrics.

Response:

{
  "totalBlocks": 5,
  "totalTransactions": 12,
  "totalVolume": 450.50,
  "totalWallets": 8,
  "pendingTransactions": 2,
  "difficulty": 2,
  "isValid": true
}

GET /validate

Validate the entire blockchain integrity.

Response:

{
  "isValid": true,
  "totalBlocks": 5
}

💼 Wallet Endpoints

POST /wallet/create

Create a new wallet with an initial balance of 1000 DAML.

Example Request:

POST /api/wallet/create
Content-Type: application/json

Response:

{
  "success": true,
  "wallet": {
    "address": "daml1a2b3c4d5e6f7g8",
    "balance": 1000,
    "createdAt": 1761687000000
  }
}

GET /wallets

Get all wallets in the network.

Response:

[
  {
    "address": "daml1a2b3c4d5e6f7g8",
    "balance": 1000,
    "createdAt": 1761687000000,
    "unlockedFeatures": ["analytics"]
  }
]

GET /wallet/:address

Get details of a specific wallet.

Parameters:

address (string, required) - Wallet address

Example Request:

GET /api/wallet/daml1a2b3c4d5e6f7g8

Response:

{
  "address": "daml1a2b3c4d5e6f7g8",
  "balance": 950,
  "createdAt": 1761687000000,
  "unlockedFeatures": ["analytics"]
}

GET /wallet/:address/balance

Get the current balance of a wallet.

Response:

{
  "address": "daml1a2b3c4d5e6f7g8",
  "balance": 950
}

GET /wallet/:address/transactions

Get transaction history for a specific wallet.

Response:

[
  {
    "id": "abc123...",
    "from": "daml1a2b3c4d5e6f7g8",
    "to": "daml9h8i7j6k5l4m3",
    "amount": 50,
    "type": "transfer",
    "metadata": { "note": "Payment" },
    "timestamp": 1761687000000,
    "blockIndex": 1,
    "blockHash": "000def...",
    "confirmed": true
  }
]

💸 Transaction Endpoints

POST /transaction/create

Create a new transaction (X402 payment).

Request Body:

from (string, required) - Sender address

to (string, required) - Recipient address

amount (number, required) - Amount to transfer

metadata (object, optional) - Additional data

Example Request:

POST /api/transaction/create
Content-Type: application/json

{
  "from": "daml1a2b3c4d5e6f7g8",
  "to": "daml9h8i7j6k5l4m3",
  "amount": 50,
  "metadata": { "note": "Payment for services" }
}

Response:

{
  "success": true,
  "transaction": {
    "id": "abc123def456...",
    "from": "daml1a2b3c4d5e6f7g8",
    "to": "daml9h8i7j6k5l4m3",
    "amount": 50,
    "timestamp": 1761687000000,
    "signature": "sha256hash..."
  }
}

GET /transaction/:id

Get details of a specific transaction.

Parameters:

id (string, required) - Transaction ID

GET /transactions/pending

Get all pending (unconfirmed) transactions.

Response:

[
  {
    "id": "abc123...",
    "from": "daml1a2b3c4d5e6f7g8",
    "to": "daml9h8i7j6k5l4m3",
    "amount": 25,
    "type": "transfer",
    "timestamp": 1761687000000
  }
]

⛏️ Mining Endpoints

POST /mine

Mine pending transactions and create a new block.

Request Body (Optional):

minerAddress (string, optional) - Address to receive mining reward

Example Request:

POST /api/mine
Content-Type: application/json

{
  "minerAddress": "daml1a2b3c4d5e6f7g8"
}

Response:

{
  "success": true,
  "block": {
    "index": 5,
    "hash": "000abc123...",
    "nonce": 1542,
    "transactions": 3,
    "timestamp": 1761687000000
  }
}

🔓 Feature Endpoints

GET /features

Get all available premium features.

Response:

[
  {
    "id": "analytics",
    "name": "Analytics Dashboard",
    "cost": 1,
    "description": "Advanced analytics and insights"
  },
  {
    "id": "api",
    "name": "API Access",
    "cost": 1,
    "description": "Full REST API access"
  },
  {
    "id": "support",
    "name": "Premium Support",
    "cost": 1,
    "description": "24/7 priority support"
  }
]

POST /feature/unlock

Unlock a premium feature for a wallet.

Request Body:

address (string, required) - Wallet address

featureId (string, required) - Feature ID (analytics, api, support)

Example Request:

POST /api/feature/unlock
Content-Type: application/json

{
  "address": "daml1a2b3c4d5e6f7g8",
  "featureId": "analytics"
}

Response:

{
  "success": true,
  "transaction": {
    "id": "abc123...",
    "featureId": "analytics",
    "cost": 1,
    "timestamp": 1761687000000
  }
}

❌ Error Responses

All endpoints may return error responses:

400 Bad Request:

{
  "error": "Missing required fields: from, to, amount"
}

404 Not Found:

{
  "error": "Wallet not found"
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "message": "Error description"
}

🔐 Authentication

Currently, the DAML Chain API does not require authentication. This is suitable for development and demonstration purposes. For production deployments, consider implementing:

API keys for endpoint access
Rate limiting
JWT tokens for user sessions
OAuth2 for third-party integrations

📊 Rate Limiting

Note: When using Vercel KV (free tier), be mindful of the 100K reads/month and 500K writes/month limits. Each API call typically performs 2-5 operations.