# RPC reference for Continuum Chain

## Direct Communication

## 1 . StreamTx 

GRPC endpoint / Kafka Producer that allows you to stream transactions in real time. Combined with colocation and running your own full node, this allows you to calculate the canonical state of the chain in **1-2 ms** at any given time.

Note that StreamTx is subject to aggressive rate limits and blocks - ensure your machine has enough RAM and bandwidth to keep up with the stream (approx 32 Mbit/s).

*Colocation Tips:* Currently the continuum sequencer operates out of EU-frankfurt Availability Zone. Select this option for \~1ms round trip latency.

## 2. SubmitTx

This allows for direct submission of transactions to continuum via grpc for minimized latency. Rate limits apply.

### RPC Endpoints

In addition, we also offer historical query APIs, via REST. you can use our official RPC endpoints, or point to any full node, to access this data.\
\
Our official RPC endpoint is: 

```
https://rpc.fermilabs.xyz/
```

#### Example usage:

```
curl https://rpc.fermilabs.xyz/status
```

#### List Blocks

Retrieve a paginated list of blocks, ordered by height (descending).

```
GET /blocks?limit=<n>&offset=<n>
```

**Parameters:**

| Parameter | Type | Default | Description                          |
| --------- | ---- | ------- | ------------------------------------ |
| `limit`   | int  | 20      | Number of blocks to return (max 100) |
| `offset`  | int  | 0       | Number of blocks to skip             |

**Example:**

```
curl "http://rpc.fermilabs.xyz/blocks?limit=10&offset=0"
```

**Response:**

```
[
  {
    "height": 3343881,
    "state_root": [18, 115, 186, ...],
    "applied_batches": 815368,
    "applied_orders": 7,
    "produced_at": 1767873641,
    "total_orders": 5,
    "total_cancels": 0,
    "batch_summaries": [...],
    "transaction_ids": ["0000000000330609-0000-0000", ...],
    "event_ids": ["0000000000330609-0001-0000", ...]
  }
]
```

***

#### Get Latest Block

Retrieve the most recent block with full transaction and event details.

```
GET /blocks/latest
```

**Example:**

```
curl "http://rpc.fermilabs.xyz/blocks/latest"
```

**Response:**

```
{
  "block": {
    "height": 3343881,
    "state_root": [...],
    "produced_at": 1767873641,
    "total_orders": 5,
    "total_cancels": 0,
    "batch_summaries": [...]
  },
  "transactions": [...],
  "events": [...]
}
```

***

#### Get Block by Height

Retrieve a specific block with full transaction and event details.

```
GET /blocks/:height
```

**Example:**

```
curl "http://rpc.fermilabs.xyz/blocks/3343881"
```

**Response:**

```
{
  "block": {
    "height": 3343881,
    "state_root": [...],
    "applied_batches": 815368,
    "applied_orders": 7,
    "produced_at": 1767873641,
    "total_orders": 5,
    "total_cancels": 0,
    "batch_summaries": [
      {
        "index": 0,
        "tick_number": 49858042756,
        "order_count": 1,
        "cancel_count": 0,
        "continuum_sequences": [11224478268823197984],
        "batch_hash": "927f4cfa6c3208163c3ef1081bf3b3d09c5a6e677c136283c152ef6dd7ae3bba"
      }
    ],
    "transaction_ids": [...],
    "event_ids": [...]
  },
  "transactions": [
    {
      "id": "0000000000330609-0000-0000",
      "block_height": 3343881,
      "batch_index": 0,
      "kind": "order",
      "market_id": "6f9ee497-1756-5bbd-b512-36cee35add8f",
      "market_name": "SOL-PERP",
      "market_kind": "Perp",
      "owner": "DeJpkURbXgmFvsi6dj9RX6rybuLiY7kgXzfFGZNWrte7",
      "side": "Sell",
      "price": 133750000,
      "quantity": 1000000000,
      "order_id": 39263332,
      "timestamp_ms": 1767871425638,
      "continuum_sequence": 11224478268823197984,
      "signature": "981259e9..."
    }
  ],
  "events": [...]
}
```

***

### Transaction Endpoints

#### Get Transaction by ID

Retrieve a specific transaction by its ID.

```
GET /transactions/:id
```

**Transaction ID Format:** `{block_height_hex}-{batch_index_hex}-{tx_index_hex}`

**Example:**

```
curl "http://rpc.fermilabs.xyz/transactions/0000000000330609-0000-0000"
```

**Response:**

```
{
  "id": "0000000000330609-0000-0000",
  "block_height": 3343881,
  "batch_index": 0,
  "kind": "order",
  "market_id": "6f9ee497-1756-5bbd-b512-36cee35add8f",
  "market_name": "SOL-PERP",
  "market_kind": "Perp",
  "owner": "DeJpkURbXgmFvsi6dj9RX6rybuLiY7kgXzfFGZNWrte7",
  "side": "Sell",
  "price": 133750000,
  "quantity": 1000000000,
  "base_mint": "11111111111111111111111111111112",
  "quote_mint": "11111111111111111111111111111113",
  "order_id": 39263332,
  "timestamp_ms": 1767871425638,
  "continuum_sequence": 11224478268823197984,
  "signature": "981259e9223eef01200204e20dfca3fb5010342363a61a2729f04d4ac5bf02798537f9359afc5d60129c241cfeb93197d7589b8751bfa7b399ee14138aeadf02"
}
```

**Transaction Kinds:**

* `order` - New order placement
* `cancel` - Order cancellation

***

### Event Endpoints

#### List Events

Retrieve a paginated list of events, optionally filtered by market.

```
GET /events?limit=<n>&offset=<n>&market_id=<uuid>
```

**Parameters:**

| Parameter   | Type   | Default | Description                          |
| ----------- | ------ | ------- | ------------------------------------ |
| `limit`     | int    | 50      | Number of events to return (max 200) |
| `offset`    | int    | 0       | Number of events to skip             |
| `market_id` | string | -       | Filter by market UUID (optional)     |

**Example:**

```
# All events
curl "http://rpc.fermilabs.xyz/events?limit=50"

# Events for specific market
curl "http://localhost:8080/events?market_id=6f9ee497-1756-5bbd-b512-36cee35add8f"
```

**Response:**

```
[
  {
    "id": "0000000000330609-0001-0000",
    "block_height": 3343881,
    "batch_index": 1,
    "market_id": "6f9ee497-1756-5bbd-b512-36cee35add8f",
    "market_name": "SOL-PERP",
    "applied_orders": 7,
    "batch_hash": "d311ca7d066a9bc2e3d9f635615dd5f8dd7871e093070d30fb1cd67fbfd4cf28"
  }
]
```

***

### WebSocket Subscriptions

#### Subscribe to New Blocks

Real-time block notifications via WebSocket.

```
WS /ws/blocks
```

**Example (using websocat):**

```
websocat ws://localhost:8080/ws/blocks
```

**Behavior:**

1. On connection, immediately receives the latest block details
2. Subsequently receives new blocks as they are produced

**Message Format:** Same as `GET /blocks/:height` response

***

### Query Patterns

#### Get Transactions in a Time Range

The API doesn't support direct time-range queries. Use this pattern:

```
# 1. Fetch blocks and filter by timestamp (produced_at is Unix timestamp)
START_TIME=1767870000
END_TIME=1767873000

curl -s "http://rpc.fermilabs.xyz/blocks?limit=1000" | \
  jq --argjson start $START_TIME --argjson end $END_TIME \
  '[.[] | select(.produced_at >= $start and .produced_at <= $end)]'

# 2. Get full details for blocks in range
curl "http://rpc.fermilabs.xyz/blocks/3343881"
```

#### Get All Transactions for a User

```
# Get user's open orders (current state)
curl "http://rpc.fermilabs.xyz/orders/user/DeJpkURbXgmFvsi6dj9RX6rybuLiY7kgXzfFGZNWrte7"

# For historical transactions, iterate through blocks
# and filter by owner field
```

#### Get Transactions for a Market

```
# Filter events by market, then fetch associated blocks
curl "http://rpc.fermilabs.xyz/events?market_id=6f9ee497-1756-5bbd-b512-36cee35add8f&limit=100"
```

#### Pagination Example

```
# Page 1 (blocks 0-99)
curl "http://rpc.fermilabs.xyz/blocks?limit=100&offset=0"

# Page 2 (blocks 100-199)
curl "http://rpc.fermilabs.xyz/blocks?limit=100&offset=100"

# Page 3 (blocks 200-299)
curl "http://rpc.fermilabs.xyzzx. /blocks?limit=100&offset=200"
```

***

### Data Models

#### BlockRecord

| Field             | Type      | Description                      |
| ----------------- | --------- | -------------------------------- |
| `height`          | u64       | Block height (sequential)        |
| `state_root`      | \[u8; 32] | Merkle root of state after block |
| `applied_batches` | u64       | Cumulative batch count           |
| `applied_orders`  | usize     | Orders matched in this block     |
| `produced_at`     | u64       | Unix timestamp (seconds)         |
| `total_orders`    | usize     | Total order transactions         |
| `total_cancels`   | usize     | Total cancel transactions        |
| `batch_summaries` | array     | Batch details (see below)        |
| `transaction_ids` | array     | Transaction IDs in this block    |
| `event_ids`       | array     | Event IDs in this block          |

#### BatchSummary

| Field                 | Type   | Description                |
| --------------------- | ------ | -------------------------- |
| `index`               | u32    | Batch index within block   |
| `tick_number`         | u64    | Continuum tick number      |
| `order_count`         | usize  | Orders in batch            |
| `cancel_count`        | usize  | Cancels in batch           |
| `continuum_sequences` | array  | Continuum sequence numbers |
| `batch_hash`          | string | SHA256 hash of batch       |

#### ExplorerTransaction

| Field                | Type   | Description                          |
| -------------------- | ------ | ------------------------------------ |
| `id`                 | string | Unique transaction ID                |
| `block_height`       | u64    | Block containing this tx             |
| `batch_index`        | u32    | Batch index within block             |
| `kind`               | string | `"order"` or `"cancel"`              |
| `market_id`          | string | Market UUID                          |
| `market_name`        | string | Human-readable market name           |
| `market_kind`        | string | `"Spot"` or `"Perp"`                 |
| `owner`              | string | Base58 public key                    |
| `side`               | string | `"Buy"` or `"Sell"` (orders only)    |
| `price`              | u64    | Price in quote units (orders only)   |
| `quantity`           | u64    | Quantity in base units (orders only) |
| `base_mint`          | string | Base token mint (orders only)        |
| `quote_mint`         | string | Quote token mint (orders only)       |
| `order_id`           | u64    | Client order ID                      |
| `timestamp_ms`       | u128   | Submission timestamp (ms)            |
| `continuum_sequence` | u64    | Continuum sequence number            |
| `signature`          | string | Ed25519 signature (hex)              |

#### ExplorerEvent

| Field            | Type   | Description                 |
| ---------------- | ------ | --------------------------- |
| `id`             | string | Unique event ID             |
| `block_height`   | u64    | Block containing this event |
| `batch_index`    | u32    | Batch index within block    |
| `market_id`      | string | Market UUID                 |
| `market_name`    | string | Human-readable market name  |
| `applied_orders` | usize  | Orders matched              |
| `batch_hash`     | string | Associated batch hash       |

***

### Node Status

#### Get Node Status

```
GET /status
```

**Response:**

```
{
  "block_height": 3343881,
  "state_root": [...],
  "applied_batches": 815368
}
```

***

### Storage Details

Block explorer data is persisted to the sled database at the path specified by `--db-path` (default: `./rollup_data`).

**Storage location:** `{db-path}/db/`

**Stored data:**

* `explorer.blocks` - Block records indexed by height
* `explorer.transactions` - Transactions indexed by ID
* `explorer.events` - Events indexed by ID

Data persists across node restarts and is automatically loaded on startup.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-v2.fermilabs.xyz/developers/rpc-reference-for-continuum-chain.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.