>

公开 REST API v1

Luno 兼容接口：行情公开，账户与交易需要 API Key。所有金额为十进制字符串，所有时间戳为毫秒。

认证

HTTP Basic：用户名为 Key ID，密码为 Secret。Authorization: Basic base64(keyId:secret)

# 推荐写法（curl 自动编码 Basic）
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/balance'

# 等价写法
curl -H "Authorization: Basic $(printf '%s:%s' "$KEY_ID" "$SECRET" | base64)" 'https://luno.local/api/1/balance'

公开端点（无需 API Key）

GET/api/1/tickers公开全部市场行情快照
示例请求 curl
curl 'https://luno.local/api/1/tickers'
返回示例
{
  "tickers": [
    {
      "pair": "XBTZAR",
      "base": "XBT",
      "counter": "ZAR",
      "timestamp": 1735689600000,
      "bid": "1267000",
      "ask": "1269000",
      "last_trade": "1268014.00",
      "open_24h": "1255000.00",
      "high_24h": "1275000.00",
      "low_24h": "1248000.00",
      "volume_24h": "12.345",
      "quote_volume_24h": "15647890.2",
      "change_24h": 1.04,
      "enabled": true,
      "halted": false
    }
  ]
}
GET/api/1/ticker公开单市场行情快照
参数必填说明
pair是交易对，例如 XBTZAR
示例请求 curl
curl 'https://luno.local/api/1/ticker?pair=XBTZAR'
返回示例
{
  "pair": "XBTZAR",
  "timestamp": 1735689600000,
  "bid": "1267000",
  "ask": "1269000",
  "last_trade": "1268014.00",
  "change_24h": 1.04
}
GET/api/1/orderbook公开盘口深度（买卖各 limit 档）
参数必填说明
pair是交易对
limit否每侧档位数，默认 100，最大 500
示例请求 curl
curl 'https://luno.local/api/1/orderbook?pair=XBTZAR&limit=50'
返回示例
{
  "pair": "XBTZAR",
  "timestamp": 1735689600000,
  "bids": [{ "price": "1267000", "volume": "0.42", "order_count": 3 }],
  "asks": [{ "price": "1269000", "volume": "0.18", "order_count": 2 }],
  "bid": "1267000",
  "ask": "1269000"
}
  • · 无撮合数据时由 Order 表按价格聚合 OPEN/PARTIAL 挂单。
GET/api/1/trades公开最近成交（倒序）
参数必填说明
pair是交易对
limit否条数，默认 100，最大 1000
since否毫秒时间戳，仅返回该时间之后的成交
示例请求 curl
curl 'https://luno.local/api/1/trades?pair=XBTZAR&limit=10'
返回示例
{
  "pair": "XBTZAR",
  "trades": [
    { "timestamp": 1735689600000, "price": "1268014.00", "volume": "0.012", "is_buy": true, "base": "XBT", "counter": "ZAR" }
  ]
}
GET/api/1/markets公开可交易市场元数据
示例请求 curl
curl 'https://luno.local/api/1/markets'
返回示例
{
  "markets": [
    {
      "market_id": "XBTZAR",
      "pair": "XBTZAR",
      "base_currency": "XBT",
      "counter_currency": "ZAR",
      "tick_size": "1",
      "lot_size": "0.00001",
      "min_notional": "10",
      "maker_fee_bps": 10,
      "taker_fee_bps": 20,
      "enabled": true,
      "halted": false,
      "ticker": { "pair": "XBTZAR", "last_trade": "1268014.00" }
    }
  ]
}
GET/api/1/candles公开K 线（按 duration 聚合）
参数必填说明
pair是交易对
since否毫秒时间戳，K 线桶起点不早于该时间
duration否周期秒数，支持 60/300/900/1800/3600/14400/86400，默认 3600
limit否条数，默认 100，最大 1000
示例请求 curl
curl 'https://luno.local/api/1/candles?pair=XBTZAR&duration=3600&limit=24'
返回示例
{
  "pair": "XBTZAR",
  "duration": 3600,
  "candles": [
    { "timestamp": 1735686000000, "open": "1267000", "high": "1269500", "low": "1266400", "close": "1268014", "volume": "0.87" }
  ]
}
  • · 库中仅有 1m K 线时，会按 duration 自动滚动聚合。

私有端点（需要 API Key）

GET/api/1/balanceAPI Key资产余额（可用 + 冻结）
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/balance'
返回示例
{
  "balance": [
    { "account_id": "acc_1", "asset": "XBT", "name": "Bitcoin", "balance": "0.512", "reserved": "0.05", "unconfirmed": "0" }
  ]
}
  • · 权限：READ_INFO
GET/api/1/accountsAPI Key账户列表（可按资产过滤）
参数必填说明
asset否资产代码，例如 XBT
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/accounts?asset=XBT'
返回示例
{
  "accounts": [
    { "id": "acc_1", "name": "Bitcoin", "asset": "XBT", "type": "SPOT", "balance": "0.512", "reserved": "0.05", "unconfirmed": "0" }
  ]
}
  • · 权限：READ_INFO
POST/api/1/accountsAPI Key创建账户（createaccount，幂等）
参数必填说明
asset是资产代码（也可用 currency）
name否可选显示名
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/accounts' \
  -H 'content-type: application/json' \
  -d '{"asset":"XBT","name":"Bitcoin"}'
返回示例
{
  "account_id": "acc_1",
  "locked_account_id": "acc_2",
  "asset": "XBT",
  "name": "Bitcoin",
  "balance": "0",
  "reserved": "0",
  "unconfirmed": "0"
}
  • · 权限：WRITE
  • · 账户由复式记账账本惰性创建，重复调用不会重复建户。
POST/api/1/postorderAPI Key下单（LIMIT / MARKET）
参数必填说明
pair是交易对，例如 XBTZAR
type是BID（买入）或 ASK（卖出），也接受 BUY/SELL
volume是基础资产数量，十进制字符串
price否限价；省略或 0 表示市价单
order_type否LIMIT 或 MARKET，默认按 price 推断
client_order_id否客户端订单号
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/postorder' \
  -H 'content-type: application/json' \
  -d '{"pair":"XBTZAR","type":"BID","volume":"0.001","price":"1265000"}'
返回示例
{
  "order_id": "clx123",
  "pair": "XBTZAR",
  "type": "LIMIT",
  "side": "BUY",
  "side_label": "BID",
  "state": "PENDING",
  "status": "OPEN",
  "limit_price": "1265000",
  "limit_volume": "0.001",
  "filled": "0",
  "remaining": "0.001",
  "average_price": "0",
  "fee_paid": "0",
  "hold_asset": "ZAR",
  "success": true
}
  • · 权限：WRITE
  • · 请求转发到撮合引擎 POST /orders（x-engine-token 内部鉴权）。
POST/api/1/stoporderAPI Key止损单（STOP_LIMIT）
参数必填说明
pair是交易对
type是BID 或 ASK
volume是数量
stop_price是触发价
price否触发后的限价，默认等于 stop_price
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/stoporder' \
  -H 'content-type: application/json' \
  -d '{"pair":"XBTZAR","type":"ASK","volume":"0.002","stop_price":"1200000","price":"1198000"}'
返回示例
{
  "order_id": "clx124",
  "pair": "XBTZAR",
  "type": "STOP_LIMIT",
  "side": "SELL",
  "state": "PENDING",
  "stop_price": "1200000",
  "limit_price": "1198000",
  "success": true
}
  • · 权限：WRITE
GET/api/1/listordersAPI Key订单列表
参数必填说明
state否PENDING（默认，含 OPEN/PARTIAL）或 COMPLETE
pair否按交易对过滤
limit否默认 100，最大 1000
offset否分页偏移
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/listorders?state=PENDING'
返回示例
{
  "orders": [
    {
      "order_id": "clx123",
      "pair": "XBTZAR",
      "creation_timestamp": 1735689600000,
      "type": "LIMIT",
      "side": "BUY",
      "state": "PENDING",
      "status": "OPEN",
      "limit_price": "1265000",
      "limit_volume": "0.001",
      "filled": "0",
      "remaining": "0.001",
      "base": "XBT",
      "counter": "ZAR"
    }
  ]
}
  • · 权限：READ_INFO
POST/api/1/cancelorderAPI Key撤单
参数必填说明
order_id是订单 ID
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/cancelorder' \
  -H 'content-type: application/json' \
  -d '{"order_id":"clx123"}'
返回示例
{ "success": true, "order_id": "clx123", "pair": "XBTZAR", "status": "CANCELLED" }
  • · 权限：WRITE
  • · 引擎不可达时在库内撤单并通过账本释放剩余冻结。
GET/api/1/orders/{id}API Key单个订单详情
参数必填说明
id是路径参数：订单 ID
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/orders/clx123'
返回示例
{
  "order_id": "clx123",
  "pair": "XBTZAR",
  "state": "PENDING",
  "status": "OPEN",
  "limit_price": "1265000",
  "limit_volume": "0.001",
  "filled": "0",
  "remaining": "0.001"
}
  • · 权限：READ_INFO
  • · 仅能查询自己的订单。
GET/api/1/transactionsAPI Key账单流水（账本分录）
参数必填说明
asset否按资产过滤
limit否默认 100，最大 1000
offset否分页偏移，回填为 row_index
from否ISO 时间下界
to否ISO 时间上界
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/transactions?limit=20'
返回示例
{
  "transactions": [
    {
      "row_index": 0,
      "timestamp": 1735689600000,
      "balance": "0.512",
      "balance_delta": "-0.001",
      "change": "-0.001",
      "currency": "XBT",
      "description": "TRADE_SETTLEMENT",
      "journal_id": "jrn_1"
    }
  ],
  "limit": 20,
  "offset": 0
}
  • · 权限：READ_INFO
POST/api/1/sendAPI Key站内转账（复式记账，两腿平衡）
参数必填说明
to是收款方邮箱 / 手机号 / 用户 ID
amount是金额，十进制字符串
asset是资产代码（也可用 currency）
description否备注
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/send' \
  -H 'content-type: application/json' \
  -d '{"to":"friend@example.com","amount":"0.001","asset":"XBT","description":"补款"}'
返回示例
{
  "success": true,
  "transfer_id": "b2c3...",
  "journal_id": "jrn_2",
  "asset": "XBT",
  "amount": "0.001",
  "recipient": { "id": "usr_2", "email": "friend@example.com", "display_name": "Friend" },
  "timestamp": 1735689600000
}
  • · 权限：WRITE
  • · 借贷两腿由 @luno/ledger post 校验 sum=0，余额不足直接 400。
GET/api/1/fee_infoAPI Key费率信息
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/fee_info'
返回示例
{
  "maker_fee": "0.001",
  "taker_fee": "0.002",
  "thirty_day_volume": "0",
  "pairs": [{ "pair": "XBTZAR", "maker_fee": "0.001", "taker_fee": "0.002", "maker_fee_bps": 10, "taker_fee_bps": 20 }],
  "withdrawal_fees": [{ "asset": "XBT", "network": "BTC", "fee": "0.0001", "min_withdraw": "0.0005" }]
}
  • · 权限：READ_INFO
GET/api/1/withdrawalsAPI Key提现记录
参数必填说明
status否按状态过滤，例如 REVIEW
limit否默认 50，最大 500
offset否分页偏移
示例请求 curl
curl -u "$KEY_ID:$SECRET" 'https://luno.local/api/1/withdrawals?limit=10'
返回示例
{
  "withdrawals": [
    { "id": "wd_1", "status": "REVIEW", "asset": "XBT", "amount": "0.01", "fee": "0.0001", "network": "BTC", "address": "bc1q...", "created_at": 1735689600000 }
  ],
  "limit": 10,
  "offset": 0
}
  • · 权限：READ_INFO
POST/api/1/withdrawalsAPI Key发起提现（进入待审并冻结）
参数必填说明
asset是资产代码
amount是提现数量
address是收款地址 / 银行账户
network否网络，默认该资产首个可用网络
memo否备注 / tag
示例请求 curl
curl -u "$KEY_ID:$SECRET" -X POST 'https://luno.local/api/1/withdrawals' \
  -H 'content-type: application/json' \
  -d '{"asset":"XBT","amount":"0.01","address":"bc1qexample","network":"BTC"}'
返回示例
{
  "id": "wd_1",
  "status": "REVIEW",
  "asset": "XBT",
  "amount": "0.01",
  "fee": "0.0001",
  "network": "BTC",
  "frozen": "0.0101",
  "note": "Withdrawal created in REVIEW state; the amount plus fee is frozen until approval."
}
  • · 权限：WRITE
  • · 创建 Withdrawal(status=REVIEW) 并将 amount+fee 从 SPOT 冻结到 LOCKED。

错误码

统一返回 { "error": "...", "error_code": "ERR_..." }

error_codeHTTP含义
ERR_INVALID_PARAMS400参数缺失、格式错误或违反业务约束
ERR_UNAUTHORIZED401缺少 / 解析失败 / Secret 不匹配的 API Key
ERR_FORBIDDEN403权限不足、账户被停用或 IP 不在白名单
ERR_RATE_LIMIT_EXCEEDED429超过 100 req/min 限额（响应带 Retry-After）
ERR_PAIR_NOT_FOUND404交易对不存在
ERR_ORDER_NOT_FOUND404订单不存在或不属于当前 Key
ERR_INSUFFICIENT_FUNDS400可用余额不足（账本拒绝记负）
ERR_MARKET_HALTED400交易对已暂停交易
ERR_ENGINE_UNAVAILABLE503撮合引擎不可达
ERR_ENGINE_REJECTED400撮合引擎拒单（精度、最小金额等）
ERR_INTERNAL500未预期的服务端错误