Skip to content

Indexer API Reference

The indexer provides a REST API for querying indexed blockchain data. All endpoints return JSON responses.

Base URL

http://localhost:8000

Response Format

Success Response

{
  "success": true,
  "data": [...]
}

Error Response

{
  "success": false,
  "error": "Error message"
}

Endpoints

Health Check

GET /

Returns service info and health status.

Response: 
{
  "success": true,
  "data": {
    "service": "Iyup Indexer API",
    "version": "1.0.0",
    "status": "healthy",
    "network": "testnet"
  }
}

Listings

GET /api/listings

Query RWA token marketplace listings.

Query Parameters:
  • status (optional): Filter by status (active, sold, cancelled)
  • seller (optional): Filter by seller address
  • tokenAddress (optional): Filter by token address
  • limit (optional): Limit results (default: 100)
  • offset (optional): Offset for pagination
Example Request: 
GET /api/listings?status=active&limit=10
Response: 
{
  "success": true,
  "data": [
    {
      "id": "listing-id",
      "tokenAddress": "0x...",
      "seller": "0x...",
      "price": "1000000000",
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z",
      "token": {
        "name": "Property #123",
        "symbol": "PROP",
        "uri": "https://..."
      }
    }
  ]
}

Get Listing by ID

GET /api/listings/:id

Get specific listing details.

Path Parameters:
  • id: Listing ID
Response: 
{
  "success": true,
  "data": {
    "id": "listing-id",
    "tokenAddress": "0x...",
    "seller": "0x...",
    "price": "1000000000",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00Z",
    "token": {
      "name": "Property #123",
      "symbol": "PROP",
      "uri": "https://..."
    }
  }
}

Documents

GET /api/documents

Query document vault records.

Query Parameters:
  • tokenAddress (optional): Filter by token address
  • issuer (optional): Filter by issuer address
  • limit (optional): Limit results (default: 100)
  • offset (optional): Offset for pagination
Example Request: 
GET /api/documents?tokenAddress=0x...
Response: 
{
  "success": true,
  "data": [
    {
      "tokenAddress": "0x...",
      "issuer": "0x...",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "versions": [
        {
          "versionIndex": 0,
          "blobId": "walrus-blob-id",
          "blobObjectId": "0x...",
          "description": "Initial document",
          "createdAt": "2024-01-01T00:00:00Z"
        }
      ],
      "auditors": []
    }
  ]
}

Get Document by Token Address

GET /api/documents/:tokenAddress

Get document record for specific token.

Path Parameters:
  • tokenAddress: RWA token address
Response: 
{
  "success": true,
  "data": {
    "tokenAddress": "0x...",
    "issuer": "0x...",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "versions": [...],
    "auditors": [...]
  }
}

ZK Commitments

GET /api/zk-commitments

Query zero-knowledge commitments.

Query Parameters:
  • tokenAddress (optional): Filter by token address
  • owner (optional): Filter by owner address
  • limit (optional): Limit results (default: 100)
  • offset (optional): Offset for pagination
Example Request: 
GET /api/zk-commitments?tokenAddress=0x...
Response: 
{
  "success": true,
  "data": [
    {
      "tokenAddress": "0x...",
      "commitment": "0x...",
      "owner": "0x...",
      "proofCount": 0,
      "lastVerifiedAt": null,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Get ZK Commitment by Token Address

GET /api/zk-commitments/:tokenAddress

Get ZK commitment for specific token.

Path Parameters:
  • tokenAddress: RWA token address
Response: 
{
  "success": true,
  "data": {
    "tokenAddress": "0x...",
    "commitment": "0x...",
    "owner": "0x...",
    "proofCount": 0,
    "lastVerifiedAt": null,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Error Handling

Common Error Codes

  • 400: Bad Request (invalid parameters)
  • 404: Not Found (resource doesn't exist)
  • 500: Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Error message description"
}

Rate Limiting

Currently, no rate limiting is enforced. Consider implementing rate limiting for production deployments.

CORS

CORS is enabled for all origins in development. Configure CORS appropriately for production.

Authentication

Currently, no authentication is required. Consider implementing authentication for production deployments.

Examples

Fetch Active Listings

const response = await fetch('http://localhost:8000/api/listings?status=active');
const { success, data } = await response.json();
 
if (success) {
  console.log('Active listings:', data);
}

Get Document for Token

const tokenAddress = '0x...';
const response = await fetch(`http://localhost:8000/api/documents/${tokenAddress}`);
const { success, data } = await response.json();
 
if (success) {
  console.log('Document:', data);
}

Query ZK Commitments

const response = await fetch('http://localhost:8000/api/zk-commitments?limit=10');
const { success, data } = await response.json();
 
if (success) {
  console.log('ZK commitments:', data);
}

Next Steps