REST API

← 概述

环境	Base URL
生产	`https://api.auroran.io`
本地开发	`http://127.0.0.1:8090`（`EXPLORER_LISTEN`）

公共约定

分页参数

参数	类型	说明
`offset`	`number`	起始偏移，默认 `0`
`limit`	`number`	页大小（各接口有独立默认值和上限）

区块、交易列表按时间新→旧；K 线按 bucket 时间旧→新。

地址与哈希

账户 / 签名者地址：0x 前缀十六进制
交易 hash、区块 digest：0x 前缀十六进制
路径 {id}：数字高度（12345）或 digest（0xabc…）；部分接口仅支持高度

Symbol 解析

多个接口通过 market_id 在内存 market cache 中解析 symbol（如 BTC-USDT）。 cache 在启动时从链节点加载；未知市场时 symbol 为 null 或省略。

Health & status

`GET /health`

存活探针。

Response 200

{ "status": "ok" }

`GET /api/v1/status`

索引同步进度与链滞后情况。

Response 200

{
  "watermark": 12345,
  "block_count": 12346,
  "node_tip": 12350,
  "behind": 5
}

Field	Type	Description
`watermark`	`number \| null`	已完全 ingest 的最高区块高度；首个区块前为 `null`
`block_count`	`number`	本地存储的区块总数
`node_tip`	`number \| null`	链节点当前 tip（节点不可达时为 `null`）
`behind`	`number \| null`	落后区块数。两者皆有：`node_tip - watermark`；仅 tip：`node_tip + 1`；否则 `null`

Blocks

`GET /api/v1/blocks`

分页区块头列表，新→旧。

Query

Param	Default	Max
`offset`	`0`	—
`limit`	`50`	`200`

Response 200

{
  "data": [
    {
      "parent": "0x…",
      "height": 12345,
      "timestamp_ms": 1717000000000,
      "digest": "0x…",
      "envelope_count": 5,
      "event_count": 42,
      "state_root": "0x…",
      "envelopes": []
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 12346 }
}

列表中 envelopes 恒为空数组。完整列表见 GET /api/v1/blocks/{id}/envelopes。

`GET /api/v1/blocks/{id}`

按高度或 digest 查询单个区块头。

Response 200

{ "data": { /* BlockHeader — 字段同列表项 */ } }

Response 404 — 区块不存在。

`GET /api/v1/blocks/{id}/events`

区块内链上事件，分页返回。

Path： {id} 必须为数字高度（不支持 digest）。

Query

Param	Default	Max
`offset`	`0`	—
`limit`	`500`	`2000`

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 0,
      "envelope_idx": 0,
      "kind": "Exec",
      "sub_kind": "Filled",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "account": "0x…",
      "body": { "price": "50000.00", "qty": "1.5" }
    }
  ],
  "page": { "offset": 0, "limit": 500, "total": 42 }
}

Field	Type	Description
`kind`	`string`	事件大类：`Exec`、`Core`、`Oco`、`Liquidation`、`Trigger`、`Bridge`、`Ops`、`Unknown`
`sub_kind`	`string`	子类型，如 `Filled`、`OrderAccepted`、`Done`
`market_id`	`number \| null`	ingest 时提取的市场 ID
`symbol`	`string \| null`	读取时从 market cache 解析
`account`	`string \| null`	关联账户（尽力提取）
`body`	`object`	节点原始事件 JSON（decimal 字符串）

`GET /api/v1/blocks/{id}/envelopes`

区块内全部 envelope（已签名交易）。

Path： {id} 必须为数字高度。

Response 200

{
  "data": [
    {
      "height": 12345,
      "envelope_idx": 0,
      "tx_hash": "0x…",
      "signer": "0x…",
      "nonce": 5,
      "status": "accepted",
      "action_kind": "PlaceOrder",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "action": { "PlaceOrder": { "market_id": 1, "side": "Bid" } },
      "reason": null
    }
  ]
}

Field	Type	Description
`status`	`string`	执行结果，如 `accepted`、`kept-reject`
`action_kind`	`string`	`action` JSON 顶层 key，如 `PlaceOrder`、`CancelOrder`
`reason`	`object \| null`	`status == "kept-reject"` 时的拒绝详情

Transactions & envelopes

`GET /api/v1/envelopes`

全局 envelope 索引，支持过滤，新→旧。

Query

Param	Type	Default	Max	Description
`signer`	`string`	—	—	按签名者过滤
`action_kind`	`string`	—	—	按 action 类型过滤
`market_id`	`number`	—	—	按市场过滤
`from_block`	`number`	—	—	最小区块高度（含）
`to_block`	`number`	—	—	最大区块高度（含）
`offset`	`number`	`0`	—	分页偏移
`limit`	`number`	`25`	`200`	页大小

Response 200

{
  "data": [ /* EnvelopeView[] */ ],
  "page": { "offset": 0, "limit": 25, "total": 1000 }
}

`GET /api/v1/tx/{hash}`

按 hash 查交易。先查本地索引，未命中则回退链节点 getTx。

Path： {hash} — 交易 hash（0x…）

Response 200（本地）

{
  "data": {
    "height": 12345,
    "envelope_idx": 0,
    "tx_hash": "0x…",
    "signer": "0x…",
    "nonce": 5,
    "status": "accepted",
    "action_kind": "PlaceOrder",
    "market_id": 1,
    "symbol": "BTC-USDT",
    "action": { "PlaceOrder": { "market_id": 1, "side": "Bid" } },
    "reason": null,
    "events": [
      {
        "height": 12345,
        "seq": 0,
        "envelope_idx": 0,
        "kind": "Exec",
        "sub_kind": "OrderAccepted",
        "market_id": 1,
        "symbol": "BTC-USDT",
        "account": "0x…",
        "body": {}
      }
    ]
  },
  "source": "local"
}

Field	Description
`source`	`"local"` — 本地索引；`"node"` — 链节点实时查询

source == "node" 时，data 遵循节点 getTx 结构，可能与 EnvelopeView 略有差异。

Response 404 — 本地和节点均未找到。

Markets

`GET /api/v1/markets`

Explorer 已知市场列表（内存 cache，来自链节点）。

Response 200 — 裸 JSON 数组：

[
  {
    "market_id": 1,
    "symbol": "BTC-USDT",
    "price_decimals": 2,
    "size_decimals": 4
  }
]

Field	Type	Description
`market_id`	`number`	链上市场 ID
`symbol`	`string`	交易对符号
`price_decimals`	`number`	价格小数位
`size_decimals`	`number`	数量小数位

Account history

`GET /api/v1/fills`

账户成交历史。每笔 fill 产生 taker / maker 两行。

Query

Param	Type	Required	Default	Max	Description
`account`	`string`	yes	—	—	账户地址
`market_id`	`number`	no	—	—	市场过滤
`from_block`	`number`	no	—	—	最小区块高度（含）
`to_block`	`number`	no	—	—	最大区块高度（含）
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 3,
      "is_taker": true,
      "timestamp_ms": 1717000000000,
      "market_id": 1,
      "order_id": 42,
      "account": "0xabcd…",
      "counterparty": "0x1234…",
      "aggressor_side": "Bid",
      "price": "50000.00",
      "qty": "1.5",
      "notional": "75000.000000",
      "fee": "3.750000",
      "symbol": "BTC-USDT"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 150 }
}

Field	Type	Description
`is_taker`	`boolean`	是否为 taker 侧
`aggressor_side`	`string`	`"Bid"`（买）或 `"Ask"`（卖），taker 方向
`notional`	`string`	`price × qty`（SCALE_6）
`fee`	`string`	该参与者手续费（SCALE_6）

`GET /api/v1/orders`

账户订单生命周期（Accepted → Resting → Done / Expired）。

Query

Param	Type	Required	Default	Max	Description
`owner`	`string`	yes	—	—	订单 owner 地址
`market_id`	`number`	no	—	—	市场过滤
`offset`	`number`	no	`0`	—	分页偏移
`limit`	`number`	no	`50`	`200`	页大小

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 1,
      "timestamp_ms": 1717000000000,
      "order_id": 100,
      "owner": "0xabcd…",
      "market_id": 1,
      "event_type": "Accepted",
      "side": "Bid",
      "price": "50000.00",
      "qty": "1.5",
      "remaining": null,
      "reason": null,
      "symbol": "BTC-USDT"
    },
    {
      "height": 12350,
      "seq": 5,
      "timestamp_ms": 1717000005000,
      "order_id": 100,
      "owner": "0xabcd…",
      "market_id": 1,
      "event_type": "Done",
      "side": null,
      "price": null,
      "qty": null,
      "remaining": "0.2",
      "reason": "Filled",
      "symbol": "BTC-USDT"
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 42 }
}

Field	Type	Description
`event_type`	`string`	`"Accepted"`、`"Resting"`、`"Done"`、`"Expired"`
`side`	`string \| null`	`"Bid"` / `"Ask"`，仅 `Accepted`
`price`	`string \| null`	限价，仅 `Accepted`
`qty`	`string \| null`	数量，仅 `Accepted`
`remaining`	`string \| null`	未成交量，`Done` / `Expired`
`reason`	`string \| null`	关闭原因，如 `"Filled"`、`"Cancelled"`

Candles (REST)

`GET /api/v1/candles`

ingest 时从 fill 预聚合的 OHLCV K 线。

Query

Param	Type	Required	Default	Max	Description
`symbol`	`string`	yes	—	—	市场符号，如 `BTC-USDT`（大小写不敏感）
`interval`	`string`	no	`1h`	—	K 线周期
`from`	`number`	no	`0`	—	起始时间（ms，含）
`to`	`number`	no	无上限	—	结束时间（ms，含）
`limit`	`number`	no	`500`	`2000`	最大返回根数

Supported interval

Value	Duration
`1m`	1 minute
`3m`	3 minutes
`5m`	5 minutes
`15m`	15 minutes
`30m`	30 minutes
`1h`	1 hour
`2h`	2 hours
`4h`	4 hours
`8h`	8 hours
`12h`	12 hours
`1d`	1 day
`3d`	3 days
`1w`	1 week

未知 interval 默认 1h。

Response 200 — Hyperliquid 兼容裸数组，按 t 升序：

[
  {
    "t": 1717000000000,
    "T": 1717003600000,
    "s": "BTC-USDT",
    "i": "1h",
    "o": "50000.00",
    "c": "50100.00",
    "h": "50200.00",
    "l": "49900.00",
    "v": "123.456",
    "n": 42
  }
]

Field	Type	Description
`t`	`number`	bucket 开盘时间（ms，对齐 interval）
`T`	`number`	bucket 收盘时间（`t + interval_ms`）
`s`	`string`	市场符号
`i`	`string`	interval 字符串
`o`, `c`, `h`, `l`	`string`	开 / 收 / 高 / 低
`v`	`string`	成交量（fill qty 之和）
`n`	`number`	成交笔数

Response 404 — symbol 不在 market cache 中。

Candles (Hyperliquid-compatible)

`POST /info`

Hyperliquid 风格 info 端点，按 body 中 type 分发。

POST /info
Content-Type: application/json

Supported types

`type`	Description
`candleSnapshot`	历史 K 线查询

未知 type 返回 400：{ "error": "unknown request type: …" }

`candleSnapshot`

Request body

{
  "type": "candleSnapshot",
  "req": {
    "coin": "BTC",
    "interval": "1h",
    "startTime": 1717000000000,
    "endTime": 1717086400000
  }
}

Field	Type	Default	Description
`req.coin`	`string`	—	币种或符号。完整符号（`BTC-USDT`）或前缀（`BTC` → `BTC-USDT`）
`req.interval`	`string`	`"1h"`	同 `GET /api/v1/candles`
`req.startTime`	`number`	`0`	起始时间（ms，含）
`req.endTime`	`number`	max	结束时间（ms，含）

Response 200 — 与 GET /api/v1/candles 相同数组格式。coin 无匹配市场时返回 []（非错误）。

单次最多 5000 根 K 线。

数据类型

BlockHeader

Field	Type	Description
`parent`	`string`	父区块 digest
`height`	`number`	区块高度
`timestamp_ms`	`number`	区块时间戳（ms）
`digest`	`string`	区块 hash
`envelope_count`	`number`	envelope 数量
`event_count`	`number`	链上事件数量
`state_root`	`string`	状态根
`envelopes`	`EnvelopeView[]`	内联 envelope（列表/仅头响应中为空）

EnvelopeView

见区块 envelopes 与全局索引。

EventView

见区块 events。

FillRecord / OrderHistoryRecord

见 fills 与 orders。

Candle（REST / WS `channel: candle`）

见 candles REST。WebSocket block_ingested 推送中的 CandleRecord 使用 snake_case（open_time_ms、interval_ms 等），详见 websocket.md。

公共约定​

分页参数​

地址与哈希​

Symbol 解析​

Health & status​

GET /health​

GET /api/v1/status​

Blocks​

GET /api/v1/blocks​

GET /api/v1/blocks/{id}​

GET /api/v1/blocks/{id}/events​

GET /api/v1/blocks/{id}/envelopes​

Transactions & envelopes​

GET /api/v1/envelopes​

GET /api/v1/tx/{hash}​

Markets​

GET /api/v1/markets​

Account history​

GET /api/v1/fills​

GET /api/v1/orders​

Candles (REST)​

GET /api/v1/candles​

Candles (Hyperliquid-compatible)​

POST /info​

candleSnapshot​

数据类型​

BlockHeader​

EnvelopeView​

EventView​

FillRecord / OrderHistoryRecord​

Candle（REST / WS channel: candle）​

公共约定

分页参数

地址与哈希

Symbol 解析

Health & status

`GET /health`

`GET /api/v1/status`

Blocks

`GET /api/v1/blocks`

`GET /api/v1/blocks/{id}`

`GET /api/v1/blocks/{id}/events`

`GET /api/v1/blocks/{id}/envelopes`

Transactions & envelopes

`GET /api/v1/envelopes`

`GET /api/v1/tx/{hash}`

Markets

`GET /api/v1/markets`

Account history

`GET /api/v1/fills`

`GET /api/v1/orders`

Candles (REST)

`GET /api/v1/candles`

Candles (Hyperliquid-compatible)

`POST /info`

`candleSnapshot`

数据类型

BlockHeader

EnvelopeView

EventView

FillRecord / OrderHistoryRecord

Candle（REST / WS `channel: candle`）