API 参考

公开的只读接口，基地址 https://api.zebra.pub。所有响应都是 JSON；金额以 wei 字符串表示（1 BNB = 10¹⁸ wei），时间是 Unix 秒。

限流与缓存

项目	规则
普通接口	每个 IP 每分钟 120 次
`/api/flap`、`/api/meta`、`/api/tx`、`/api/bind/*`	每个 IP 每分钟 30 次（要读链、模拟执行或调用 Flap）
超限	返回 `429`，正文含 `retry_after_s`
缓存	响应带 `cache-control` 和 `x-cache: HIT/MISS`；同一 URL 在缓存期内返回同一份数据

接口	缓存
`/api/launches`、`/api/launch/*`、`/api/recent`	3 秒
`/api/me/`、`/api/airdrops`	5 秒
`/api/stats`、`/api/profile/*`	10 秒
`/api/dao`、`/api/hot`	15 秒
`/api/name/`、`/api/address/`、`/api/search`	30 秒
`/api/flap`、`/api/flap/estimate`、`/api/vanity`、`/api/timeline`	60 秒
`/api/binding/*`	3 秒
`/api/decode`	5 分钟
`/api/health`、`/api/meta`、`/api/admin/`、`/api/tx`、`/api/bind/*`	不缓存

需要更高频率，请直接读链上事件（见合约）。

首发

`GET /api/launches`

首发列表。默认先列认购中、再已募满、再已发射，同组内按排序条件。

参数	说明
`sort`	`progress`（默认，认购进度）· `people`（人数）· `amount`（金额）
`stage`	`Open` · `Full` · `Launched` · `Done` · `Refunding`，不填为全部
`limit`	默认 50，最大 200

每一项包含：address、creator（发起交易的地址）、creator_id（发行人代表的 Agent ID 地址，可能是它自己，也可能是它绑定到的 ID；没有为 null）、creator_name、template_id（玩法模板，0 = 经典）、binding（这一轮锁定的绑定合约）、kind（TaxV6/TaxV6Vault/PlainV7）、name、symbol、meta、pool、quote_token、slip_bps、fee_bps、buy_tax_bps、sell_tax_bps、min_per_id、max_per_id、target、raised、left_bnb、progress（0–1，认购进度）、subscribers、stage、created_time、filled_at、launched_at、graduated_at（在 Flap 毕业、流动性迁移到 DEX 的时间）、token、spent、tokens_bought、fee_charged。

`GET /api/launch/:addr`

单个首发的全部字段，加上当前认购者列表（subscribers：who 是付款和收款的地址，id 是它算在哪个 Agent ID 名下，name 是该 ID 的名字；用绑定钱包认购时 who ≠ id）、退出和分发记录，以及 stats：

字段	说明
`first_sub_time`、`exits`、`exited_people`	第一笔认购时间、退出次数和人数
`distributed`、`distributed_at`	分发到账人数和完成时间
`graduated_at`、`dex_pool`	毕业时间和 DEX 池子地址
`holders`	发射后持有这个代币的地址数（由代币的链上转账逐笔计算）
`real_holders`、`real_share`	其中持有 Agent ID 的真人人数，以及他们合计持有的供应量比例（0–1）
`top10_share`	最大的 10 个持有人合计比例，不计合约地址（内盘、DEX 池子、首发合约），除非该合约本身持有 Agent ID

`GET /api/launch/:addr/wall`

名字墙：认购事件流（认购、追加、退出），limit 默认 100，最大 500。

`GET /api/me/:addr`

addr 也可以是名字（带不带 .ai 都行），查看不需要连接钱包。某个地址的 Agent ID、参与和发起的首发、认购额，以及收到的 DAO 空投（airdrops：每个批次每种代币一条，含金额、是否到账、交易哈希）。参与的首发另含 my_balance（当前持仓）、my_since（这次持有开始的时间）、my_received、my_refunded、my_exit_back；my_payee 是这一轮实际付款和收款的地址（ID 用绑定钱包认购时就是那个钱包）。查的是 Agent ID 时，绑定钱包代它认购的首发也列在里面。binding 同下面 /api/binding 的前三个字段。profile 同下。

`GET /api/profile/:id`

名片数据，id 是名字（可带 .ai）或地址。profile 含 joined（参加过的首发数）、at_launch（发射时仍在的场数）、created、holding（仍持有的首发代币数）、hold_days（持有最久的那个代币已连续持有的天数）、airdrops（收到过的空投批次数）、early（前 5 万个领取）和 pending_airdrops（发放中、还没到账的空投，按代币合计）。

`GET /api/hot?limit=10`

真人热度榜：认购中的首发按当前认购人数，已发射的按持有 Agent ID 的真人持有人数（real_people），从多到少，最多 50 个。

钱包绑定

`GET /api/binding/:who`

who 是地址或名字。返回：

字段	说明
`contract`	新首发使用的绑定合约
`wallet`	`who` 是 Agent ID 时：它绑定的钱包（`address`、`bound_at`、`tx`），没有为 `null`
`id`	`who` 是钱包时：它代表的 Agent ID（`address`、`name`、`bound_at`、`tx`），没有为 `null`
`next_bind_at`、`nonce`	Agent ID：最早可以再绑定的时间（`0` = 现在）、当前签名序号
`wallet_free_at`	钱包：最早可以被绑定的时间（`0` = 现在）
`history`	最近 50 条绑定记录：`kind`（`bound` / `unbound` / `revoked`）、`id_addr`、`wallet`、`detail`（解绑方式 `wallet` / `id` / `id_signature` / `replaced`）、`block_time`、`tx_hash`

交给 Agent 的接口（单号）

Agentic Wallet 只能通过对话操作。这几个接口把一笔交易或一份待签授权准备好、检查好，存成一个 6 位单号（30 分钟有效，只能取一次），由 Agent 用 Zebra 技能取回执行。只会生成调用 Zebra 首发合约或绑定合约的内容，永远不会生成代币授权或转账。

`POST /api/tx`

json

{ "action": "subscribe", "launch": "0x…", "from": "0x…", "amount": "0.05" }

字段	说明
`action`	`subscribe`（认购或追加）· `exit` · `claim` · `refund` · `withdraw` · `withdraw_tokens`
`launch`	首发合约地址
`from`	将要发出交易的地址（Agentic Wallet 地址或绑定钱包）
`amount`	认购金额，单位 BNB（也可用 `amount_wei`）；只有 `subscribe` 需要
`lang`	可选，`en` 时 `summary` 用英文（默认中文）；`/api/bind/request` 同样支持

后端依次检查：首发存在且阶段正确；from 代表哪个 Agent ID；这个 ID 这一轮是否已用别的地址认购；金额是否在每人上下限和剩余额度内；最后用 from 模拟执行。不通过返回 400：{"error": "中文原因", "code": "错误代码"}。通过返回：

json

{ "kind": "tx", "code": "NHJQU3", "expires_at": 1793008991, "chain_id": 56, "action": "subscribe",
  "launch": "0x…", "from": "0x…", "to": "0x…", "value": "50000000000000000", "value_bnb": "0.05",
  "data": "0x8f449a05", "function": "subscribe()", "summary": "认购 0.05 BNB 到首发 HERD（0x…），代表 xxx.ai；代币和退款都发到 0x…" }

`POST /api/bind/request`

json

{ "name": "alice", "wallet": "0x…" }        // 绑定
{ "action": "unbind", "name": "alice" }     // 解绑当前钱包

检查名字、冷却期和占用情况，返回待签的 EIP-712 授权：kind: "sign"、code、signer（Agent ID 地址）、wallet、binding、deadline、digest（合约算出的摘要，用来核对签名）、summary，以及 typed_data（domain 为 Zebra Binding / 1 / 56 / 绑定合约，primaryType 为 Bind 或 Unbind，可直接交给 eth_signTypedData_v4）。

`GET /api/tx/:code`

Agent 用单号取回上面两种内容之一（原样，含 typed_data 的字段顺序）。只能取一次：再取返回 410（CodeUsed）；过期返回 410（CodeExpired）；不存在返回 404。

错误代码

合约用错误代码报错，Agent 的预览里可能只显示一串十六进制。

接口	说明
`GET /api/decode?data=0x…`	把报错数据（或包含它的整段报错文字）翻成中文：`code`、`selector`、`text`
`GET /api/errors`	全部错误代码、4 字节选择器和中文说明

斑马 DAO

`GET /api/dao`

累计进账（launch_fees、exit_fees、swept）、最近的资金流水，以及多签钱包 safe：地址、实时 BNB 余额（bnb_wei）、成员（owners）和签名门槛（threshold）。

totals：税收佣金（commission_bnb）、捐赠（donations_bnb、donations 笔数，含代币捐赠）、支出（spent_bnb，其中买入代币 spent_buy_bnb、其他 spent_other_bnb）、airdrop_batches、airdrop_people。

ledger：多签的收支明细，最新在前。每条含 dir（in / out）、kind、time、tx、n（笔数）和金额：

`kind`	含义
`launch_fee` · `exit_fee` · `sweep`	首发手续费、退出手续费（同一场首发同一天合并）、清扫零头
`tax_commission`	带税币的 Flap 税收佣金（`symbol` 为来源代币；非 BNB 池以池子币到账时带 `token_symbol`、`decimals`）
`donation`	别人直接转给多签的 BNB
`token_in`	转入多签的代币（`token_symbol`、`decimals`）
`buy` · `spend`	多签发出的 BNB：给 Flap 或 PancakeSwap 合约记为买入，其余记为支出（MultiSend 里的每一笔都单独计）
`airdrop` · `token_out`	多签转出的代币，同一笔交易合并为一条（`tokens` 列出每种代币）；对上空投批次的带 `batch_id`、`batch_name`

`GET /api/airdrops`

已公开的空投批次（发放中、已完成、已取消），最新在前。每项含 id、name、note、rule（all_ids / launches / custom）、tokens（每种代币的 token、symbol、decimals、total_wei、sent_wei）、recipients、sent（已全部到账的人数）、transfers、transfers_sent、status（active / done / cancelled）、created_at、published_at、done_at、snapshot_block。

`GET /api/airdrops/:id`

单个批次和名单（分页）。参数：page、size（最大 500）、q（地址或名字前缀）、status（pending 还有没到账的 / sent 全部到账）。名单每项含 address、handle、status（pending / partial / sent）和 items（每种代币一条：pos、amount_wei、status、tx_hash、sent_at）。

`GET /api/airdrops/:id/csv`

完整名单的 CSV 下载，每人每种代币一行，含到账状态。

Flap 参数

`GET /api/flap`

zebra 字段是工厂当前给新首发的设置：factory、binding、fee_bps、min_target / max_target（募资目标范围，wei）、min_per_id_floor、official_vaults_only、twap_window、paused，以及 templates（每个模板的 id、name、impl、status、ready_at；生效中的模板带 creation_cost，即创建首发要付的金额）。

其余是从链上读取的 Flap 当前参数：Portal 版本、交易手续费（bps）、BNB 曲线（r、h、k、毕业储备）、已开放的池子及其均价路径。池子的 enabled 要求 Flap 已开放 BNB 兑换，且路径上的池子价格记录已满 1800 条（oracle_ready），否则工厂不允许在这个池子上创建首发。

`GET /api/flap/estimate?progress=58&pool=BNB`

按 BNB 曲线估算达到某个发射后内盘进度所需的募资额。progress 取值 (0, 100]；非 BNB 池在 100% 时含 20% 余量。

Logo 上传

`POST /api/meta`

创建首发时用：把代币 Logo 和简介等信息上传到 Flap，固定在 IPFS 上，返回一个 cid。这个 cid 就是创建代币时的 meta 字段，Flap 和 zebra.pub 都从它读取 Logo 和链接。浏览器直接调用 Flap 的上传接口会遇到跨域限制，所以由我们的后端转发。

请求为 multipart/form-data：

字段	必填	说明
`image`	是	Logo 图片文件（`image/*`），不超过 2 MB；建议正方形 PNG / JPG / WebP，512×512 以上
`description`	否	代币简介，最多 600 字符
`website`	否	官网链接
`twitter`	否	X 链接
`telegram`	否	Telegram 链接

成功返回 200：

json

{ "cid": "bafkreictuhft3yl5icnswbh52nhth3sjjcgrk7d4qnxglhuqehwgfznw3q" }

cid 指向一份 JSON（description、website、twitter、telegram、image 等），其中 image 是图片自己的 CID。可以通过 Flap 的网关查看，例如 https://flap.mypinata.cloud/ipfs/<cid>。

状态码	含义
`400`	没有图片、图片超过 2 MB、文件不是图片，或表单格式不对
`429`	超过频率限制（每个 IP 每分钟 30 次，与 `/api/flap*` 共用）
`502`	Flap 上传失败，或返回里没有 `cid`（正文 `detail` 带 Flap 的错误信息）

示例：

bash

curl -X POST https://api.zebra.pub/api/meta \
  -F "image=@logo.png;type=image/png" \
  -F "description=一句话介绍" \
  -F "website=https://example.com" \
  -F "twitter=https://x.com/example"

上传的内容会永久公开在 IPFS 上，无法删除，请只上传要用于代币的正式素材。

其他

管理后台的 /api/admin/* 只供 DAO 多签成员使用（钱包签名登录），不在此列出。

Agent ID

接口	说明
`GET /api/stats`	Agent ID 总数和增长统计
`GET /api/name/:handle`	按名字查（不含 `.ai`）
`GET /api/address/:addr`	按地址查
`GET /api/search?q=`	名字前缀搜索，最多 20 条
`GET /api/recent?limit=`	最新注册，默认 50，最大 200
`GET /api/timeline?bucket=3600&hours=72`	注册时间分布
`GET /api/vanity`	三字符名字、吉利数字名字、最早的名字
`GET /api/health`	服务状态和缓存统计

API 参考 ​

限流与缓存 ​

首发 ​

GET /api/launches ​

GET /api/launch/:addr ​

GET /api/launch/:addr/wall ​

GET /api/me/:addr ​

GET /api/profile/:id ​

GET /api/hot?limit=10 ​

钱包绑定 ​

GET /api/binding/:who ​

交给 Agent 的接口（单号） ​

POST /api/tx ​

POST /api/bind/request ​

GET /api/tx/:code ​

错误代码 ​

斑马 DAO ​

GET /api/dao ​

GET /api/airdrops ​

GET /api/airdrops/:id ​

GET /api/airdrops/:id/csv ​

Flap 参数 ​

GET /api/flap ​

GET /api/flap/estimate?progress=58&pool=BNB ​

Logo 上传 ​

POST /api/meta ​

其他 ​

Agent ID ​

API 参考

限流与缓存

首发

`GET /api/launches`

`GET /api/launch/:addr`

`GET /api/launch/:addr/wall`

`GET /api/me/:addr`

`GET /api/profile/:id`

`GET /api/hot?limit=10`

钱包绑定

`GET /api/binding/:who`

交给 Agent 的接口（单号）

`POST /api/tx`

`POST /api/bind/request`

`GET /api/tx/:code`

错误代码

斑马 DAO

`GET /api/dao`

`GET /api/airdrops`

`GET /api/airdrops/:id`

`GET /api/airdrops/:id/csv`

Flap 参数

`GET /api/flap`

`GET /api/flap/estimate?progress=58&pool=BNB`

Logo 上传

`POST /api/meta`

其他

Agent ID