Explorer API

We built the Explorer API to make blockchain data easy to query for dashboards, analytics, and integrations. The Citrate Explorer API provides a RESTful interface for querying indexed blockchain data. It powers the Citrate block explorer and is available for third-party integrations, analytics dashboards, and monitoring tools.

Base URL

http://localhost:4000

All endpoints return JSON responses. No authentication is required for read-only explorer queries.

Block Endpoints

List Blocks

GET /explorer/blocks

Returns a paginated list of recent blocks, ordered by block number descending.

Query Parameters:

Parameter	Type	Default	Description
limit	int	20	Number of blocks to return (max 100)
offset	int	0	Pagination offset
miner	string	...	Filter by miner address

Response:

{
  "data": [
    {
      "hash": "0xblock1...",
      "number": 14523,
      "parentHash": "0xparent...",
      "timestamp": 1709145900,
      "miner": "0xminer...",
      "gasUsed": 21000,
      "transactionCount": 5,
      "blueScore": 14201
    }
  ],
  "total": 14523,
  "limit": 20,
  "offset": 0
}

Get Block

GET /explorer/blocks/:hash_or_height

Returns a single block by its hash or block height. Includes full transaction list.

Response:

{
  "hash": "0xblock1...",
  "number": 14523,
  "parentHash": "0xparent...",
  "timestamp": 1709145900,
  "miner": "0xminer...",
  "gasUsed": 21000,
  "gasLimit": 30000000,
  "baseFeePerGas": "0x3b9aca00",
  "blueScore": 14201,
  "dagParents": ["0xparent1...", "0xparent2..."],
  "transactions": [
    {
      "hash": "0xtx1...",
      "from": "0xsender...",
      "to": "0xrecipient...",
      "value": "1000000000000000000",
      "gasUsed": 21000
    }
  ]
}

Transaction Endpoints

List Transactions

GET /explorer/transactions

Returns a paginated list of recent transactions.

Query Parameters:

Parameter	Type	Default	Description
limit	int	20	Number of transactions to return
offset	int	0	Pagination offset
from	string	...	Filter by sender address
to	string	...	Filter by recipient address
type	string	...	Filter by type: transfer, contract, inference

Response:

{
  "data": [
    {
      "hash": "0xtx1...",
      "blockNumber": 14523,
      "from": "0xsender...",
      "to": "0xrecipient...",
      "value": "1000000000000000000",
      "gasUsed": 21000,
      "status": "success",
      "timestamp": 1709145900,
      "type": "transfer"
    }
  ],
  "total": 89421,
  "limit": 20,
  "offset": 0
}

Get Transaction

GET /explorer/transactions/:hash

Returns a single transaction by its hash, including receipt data and logs.

Response:

{
  "hash": "0xtx1...",
  "blockHash": "0xblock1...",
  "blockNumber": 14523,
  "from": "0xsender...",
  "to": "0xrecipient...",
  "value": "1000000000000000000",
  "gasUsed": 21000,
  "gasPrice": "1000000000",
  "nonce": 42,
  "input": "0x...",
  "status": "success",
  "timestamp": 1709145900,
  "logs": [
    {
      "address": "0xcontract...",
      "topics": ["0xevent..."],
      "data": "0x..."
    }
  ]
}

Account Endpoints

List Accounts

GET /explorer/accounts

Returns a paginated list of accounts, ordered by balance descending.

Query Parameters:

Parameter	Type	Default	Description
limit	int	20	Number of accounts to return
offset	int	0	Pagination offset

Get Account

GET /explorer/accounts/:address

Returns account details including balance, transaction count, and contract information if applicable.

Response:

{
  "address": "0xaccount...",
  "balance": "5000000000000000000",
  "transactionCount": 156,
  "isContract": false,
  "firstSeen": 1709100000,
  "lastActive": 1709145900
}

DAG-Specific Endpoints

These endpoints expose the GhostDAG structure that underlies Citrate's consensus mechanism.

Get DAG Tips

GET /explorer/dag/tips

Returns the current set of DAG tips (blocks with no children).

Response:

{
  "tips": [
    {
      "hash": "0xtip1...",
      "number": 14523,
      "timestamp": 1709145900,
      "blueScore": 14201
    },
    {
      "hash": "0xtip2...",
      "number": 14522,
      "timestamp": 1709145898,
      "blueScore": 14200
    }
  ],
  "tipCount": 2
}

Get Blue Set

GET /explorer/dag/blueSet/:blockHash

Returns the blue set (honest majority blocks) for a given block within the GhostDAG ordering.

Response:

{
  "blockHash": "0xblock...",
  "blueSet": ["0xblue1...", "0xblue2...", "0xblue3..."],
  "blueScore": 14201,
  "redSet": ["0xred1..."]
}

Get DAG Stats

GET /explorer/dag/stats

Returns aggregate statistics about the GhostDAG.

Response:

{
  "depth": 14523,
  "width": 3,
  "blueScore": 14201,
  "avgConfirmationTime": 1.2,
  "avgBlockRate": 0.85,
  "tipsCount": 2,
  "totalBlocks": 14800,
  "orphanRate": 0.019
}

Model Registry Endpoints

List Models

GET /explorer/models

Returns a paginated list of AI models registered on-chain.

Query Parameters:

Parameter	Type	Default	Description
limit	int	20	Number of models to return
offset	int	0	Pagination offset
format	string	...	Filter by format (onnx, gguf)
owner	string	...	Filter by owner address

Response:

{
  "data": [
    {
      "modelId": "0xmodel1...",
      "name": "sentiment-v1",
      "format": "onnx",
      "owner": "0xowner...",
      "deployedAt": 14200,
      "inferenceCount": 4521
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Get Model

GET /explorer/models/:modelId

Returns full metadata for a single model.

Response:

{
  "modelId": "0xmodel1...",
  "name": "sentiment-v1",
  "format": "onnx",
  "owner": "0xowner...",
  "modelHash": "0xhash...",
  "storageUri": "ipfs://Qm...",
  "deployedAt": 14200,
  "inferenceCount": 4521,
  "lastInference": 1709145800,
  "inputSchema": { "type": "string", "maxLength": 512 },
  "outputSchema": { "type": "object" }
}

Search

Universal Search

GET /explorer/search/:query

Searches across blocks, transactions, accounts, and models. The query can be a block hash, transaction hash, account address, block height, or model name.

Response:

{
  "type": "transaction",
  "result": {
    "hash": "0xtx1...",
    "blockNumber": 14523,
    "from": "0xsender...",
    "to": "0xrecipient...",
    "value": "1000000000000000000"
  }
}

Possible type values: block, transaction, account, model, not_found.

Error Responses

HTTP Status	Description
400	Invalid query parameters
404	Resource not found
500	Internal server error

Error response body:

{
  "error": {
    "code": "not_found",
    "message": "Block with hash 0xinvalid... not found."
  }
}