Frontend APIs

2026-09-16 全新部署接入：Polygon · 测试充值资产 · 真实 UMA。充值仅 mUSDT/mUSDC；USDC.e 仅用于 UMA 保证金。服务版本核验通过后开放交易，不提供旧开发版本入口。运行地址以合约目录的统一 SDK 清单为准。

线上环境

核对日期：2026-09-12。本文公开说明官网前端依赖的接口；不包含已下线游戏、管理后台接口、私钥、内部服务器地址或任何服务密钥。公共响应中的额外兼容字段不代表对应产品仍在开放。

例如代币列表完整地址为 https://wf.vip/backend/api/v1/tokens，3D 当前轮次为 https://wf.vip/indexer/lotto3d/current。不要漏掉 /backend 或 /indexer 前缀。

查看线上部署清单 · 前端健康检查

线上公开读取已核查；需要用户签名、充值授权、申请、账单修改或链上交易的写路径没有为发布文档而执行。请求/响应契约按已发布版本的对应实现核对，不将“路由存在”写成“全部资金流程已实测”。下文配置默认值和保留封装是排错参考，不是推荐使用本地地址接入。

1. 总览

业务资金写入不是通过 Backend 的订单接口完成：购票直接调用 V4 Ledger，充值/提现调用 StablecoinReserve，领奖调用游戏或 Settlement 合约。Indexer 扫描链上事件供页面展示。

2. 地址、鉴权和数据约定

2.1 Base URL

后续 Backend 表格路径都拼接 BACKEND_API_BASE_URL；Indexer 表格路径都拼接 INDEXER_API_BASE_URL。

NEXT_PUBLIC_* 会进入浏览器构建产物，不能放私钥或服务端密钥。本文不记录真实 RPC 凭证、API Key 或会话 Token。代码仍有 RPC 网关兜底；若部署要求直连，必须正确设置 RPC URL，不能仅凭产品要求推断当前环境已直连。线上地址以上方环境表为准，服务端私密 RPC 凭证不公开。

2.2 通用约定

没有统一的 { data, code, message } 成功包裹，必须按每个接口的返回结构读取。失败也不统一：Backend 常见 {error, code}，钱包登录路由常仅有 {error}，RPC 使用 JSON-RPC error。

3. Backend 接口清单

以下 17 个接口均有当前前端调用链。除注明外成功状态为 200。

3.1 B01 产品准入

无查询参数，浏览器不自行指定国家。返回：

Cache-Control: private, no-store。前端 5 秒超时，未取得 allowed=true 不展示被准入边界包裹的参与操作。不能把准入接口返回值当成合约授权。

3.2 B02 游戏读取状态

无参数。当前前端使用的返回字段为 {deploymentId, source:"bff", lotto3d, generatedAt}，忽略其他兼容字段。

当前 Backend 读取 3D 的 paused、ticketPrice 和 Treasury accumulatedPool。

失败：503 {error, code:"GAME_READ_STATE_UNAVAILABLE"}。

3.3 B03 World Lotto 聚合快照

无参数。无轮次返回 null，有轮次返回：

Backend 聚合 Indexer /lotto-uma/current 和三个合约读取；任一必需依赖失败可能返回 503 {error, code:"UMA_SNAPSHOT_UNAVAILABLE"}。前端没有在 BFF 失败时自动改读 Indexer current 的实现。

3.4 B04 来源计划和证据

路径 roundId 为十进制轮次 ID；实现仅接受 1～12 位数字且排除字符串 "0"，不符合会走无计划结果。返回：

数据来自 Backend 中状态为 EXECUTED 的创建轮次和 UMA 断言管理操作记录，不是前端读取链上国家列表。sourceConfigHash 存在不代表接口替调用方验证了证据内容。

无有效创建记录或不足 7+2 来源：404 {error,code:"SOURCE_PLAN_NOT_FOUND"}，前端转为 null。服务异常：503 SOURCE_PLAN_UNAVAILABLE。公开缓存 30 秒。

3.5 B05 白名单代币

返回 {tokens:[{symbol:string,address:string,decimals:number}]}。地址来自当前配置；不要把 mUSDC/mUSDT 自动换成同名官方资产。只返回公开代币信息，不返回充值限额或风控内部阈值。

3.6 B06 充值授权

请求字段全部必填：

返回 {user,token,amount,deadline,nonce,signature}，全部为 string；deadline 是 Unix 秒，signature 是服务端 EIP-712 签名。返回 amount 在签名结构里名为 authorizedAmount。

新部署处理过程：固定资产白名单 → 地址风险筛查 → nonce → 签名 → 授权审计记录。该接口不是充值交易，不会直接增加 WUSD。Reserve 无单笔或每日数量上限；后台是否仍返回旧额度错误必须在服务切换时核验。

当前路由格式正则为纯数字，零值快捷判断只匹配 "0"；对接方不要用 "00" 等非规范写法依赖服务端纠正。链上仍会拒绝零额充值。

3.7 B07～B09 钱包登录

1. POST challenge：请求 {address}，地址必须合法，不接受多余字段；Origin 必须在 Backend CORS 允许范围内。返回 {id,message,expiresAt}；id 为 UUID，消息为 SIWE，挑战 5 分钟有效。
2. 钱包签署服务端原始 message。前端校验地址、站点 domain、URI、chainId、过期时间，不能自行改写消息。
3. POST verify：请求 {id,signature}；signature 为带 0x 的完整字节串，最长 8194 字符，不接受多余字段。返回 {token,address,expiresAt}，会话有效期 8 小时。
4. 私有请求携带 Bearer token。该 token 是 64 位小写十六进制随机串，不是 JWT，也不是 partnerCode。
5. DELETE session：无需请求体，返回 {ok:true}。缺失/失效 token 不视为成功注销。

挑战单次消费。前端 token 只存在 React 内存中；刷新页面、换账号、换链、换连接器、断开钱包都会失去本地登录会话。连接钱包不等于取得 Backend 登录身份。

错误：400 参数错误；401 挑战过期/已使用/签名无效；403 Origin 不允许；503 登录服务/RPC 不可用。登录路由组每 IP 每分钟 20 次，超限 429 使用限流中间件默认响应，不保证 JSON。私有接口通用鉴权错误为 WALLET_AUTH_REQUIRED 或 WALLET_AUTH_FAILED。

3.8 B10～B12 通知

GET 返回 {notifications,unreadCount}，按 createdAt 倒序最多 50 条：

unreadCount 是这次返回的最多 50 条里的未读数，不是完整历史未读总数。读取列表时服务端会尝试同步自动通知，因此该 GET 不只是读取数据库。

单条已读：路径 id，空请求体，返回 {ok:true}；非本人通知或不存在返回 404 NOTIFICATION_NOT_FOUND。全部已读：空请求体，返回 {ok:true,updated:number}，会更新当前钱包全部未读通知，不限最近 50 条。

3.9 B13 合作方申请

以下除 payoutAddress 外全部必填，不接受额外字段：

成功 201 {applicationNo,status}，编号形如 WF-P-YYYYMMDD-XXXXXXXX。同 submissionToken 返回原申请，不覆盖已提交资料。新申请默认 SUBMITTED；审核状态还可能为 BUSINESS_REVIEW / RISK_REVIEW / TECHNICAL_VERIFICATION / APPROVED / REJECTED。

失败：400 INVALID_PARTNER_APPLICATION；429 PARTNER_APPLICATION_RATE_LIMITED，每 IP 每小时 5 次。此接口不返回 API Key，也不在提交时直接返回已批准的 partnerCode。当前前端没有申请查询或审核 API。

3.10 B14～B17 合作方控制台

partnerId 是数据库 Partner ID，不是公开渠道 code。partnerCode 不是登录凭证。

成员查询 B14：无参数，返回 {memberships:[{id,role,partner}]}。仅返回当前钱包 ACTIVE 成员关系，按成员创建时间升序。role 为 OWNER / FINANCE / VIEWER。partner 包含：

版本对象共同字段：id,partnerId,version,effectiveFromBlock,effectiveToBlock,reason,createdBy,createdAt；区块为字符串，截止区块可为 null 且为开区间。佣金版本多 shareBps:number，状态版本多 status。

订单查询 B15：可选 query cursor，当前实现是从 0 开始的 offset，不是不透明游标；每次固定最多 100 条，按 blockNumber、logIndex 倒序。返回 {items,nextCursor}；nextCursor 为字符串或 null。页面目前未消费 nextCursor，因此只显示第一批，并用这一批计算概览的已归因佣金，不能当成全历史累计。

每项订单返回 PartnerChainPurchase 的标量字段和 commission：

commission 返回字段：

reversal 字段：id,commissionEntryId,partnerId,statementId,grossCommissionAmount,commissionAmount,platformRemainderAmount,reasonCode,evidenceBlock,evidenceTxHash,createdAt。金额为字符串；evidenceBlock 是字符串/null；statementId、evidenceTxHash 可空。

账单查询 B16：无分页参数，固定取 periodEnd 倒序最多 100 份，返回 {statements:[...]}。

账单决定 B17：body {action:"confirm"|"dispute",reason?:string}。reason 去首尾空格后最长 2000 字符，dispute 至少 10 字符。只允许 ISSUED 状态；confirm 后为 CONFIRMED，dispute 后为 DISPUTED。返回 {statement}，标量字段同上，但不包含查询接口的 _count。

错误：403 PARTNER_CONSOLE_FORBIDDEN / PARTNER_STATEMENT_FORBIDDEN；400 INVALID_STATEMENT_DECISION；404 PARTNER_STATEMENT_NOT_FOUND；409 PARTNER_STATEMENT_STATE_CONFLICT；另有通用钱包鉴权错误。确认账单不是发起链上付款，页面不执行 Safe 打款。

4. Indexer REST 接口清单

本节都是 GET，无 Bearer。用户地址虽经页面登录/连接后才用于查询，服务端这些 REST 路由本身是公开链上数据查询。

P<T> 表示 {items:T[],page:number,pageSize:number,hasMore:boolean}。page 从 1 开始；服务端默认 pageSize=10，上限 50。前端封装默认轮次 6、票据历史 8；部分市场页显式传 8。没有 total 字段。调用方应传正整数；服务端用 Number 和范围夹取，并非所有非法格式都返回统一 400。

“保留”指没有当前页面调用链，不能作为已启用功能。编号保留原有引用，已下线游戏对应的编号不再列出。

4.1 特殊查询语义

I15 在最近 20 个轮次中优先选正在销售的 Open 轮次，其次最早即将开始的 Open 轮次，然后未解决的 Open/SalesClosed 轮次，最后才回退最新记录。它不等于最大 roundId。

I14 默认 includeLatest=false 跳过数据库最新一轮，true 不跳过。I21 固定跳过最新记录，不保证历史列表只含已开奖轮次。

I05 返回 {deploymentId,source:"ponder",address,hasPendingPrize,totalCount,games,items}。games 包含当前产品的 lotto3d、lotto7uma 计数，也可能包含兼容字段；items 为 {game,roundId,ticketId,tier,amount}。tier 为数字，amount 为 WUSD 字符串。该查询各游戏最多扫描 500 条购票记录，因此不是无限历史的完整资金审计 API。无效地址返回 400 {code:"INVALID_WALLET"}。

I06 的前端类型只声明 {allocationVersion,prizeBps,datBps,partnerBps,opsBps}，均为 number。服务端还返回 id,gameKey,treasury,txHash 字符串，roundId,blockNumber,blockTimestamp 整数串，以及 deploymentId,indexedBlock,chainHead,finalityStatus,dataTimestamp 元数据；indexedBlock/chainHead 可空。它描述链上轮次资金分配，不是合作方最终 Web2 返佣比例；当前购票页不调用它。错误为400 INVALID_GAME_ADDRESS / INVALID_ROUND_ID，404 GAME_NOT_FOUND / ROUND_ALLOCATION_NOT_FOUND。

这里 finalityStatus 的实现是根据索引落后区块数推导的 finalized / pending / unknown 展示标签，不是对某笔交易不可重组的证明。

Indexer 前端客户端每次请求设置 8 秒超时。多数路由没有独立业务错误包装；不要假定所有非 2xx 返回同一种 JSON。活动接口有专门的 503 错误处理。字段缺失/null 和金额为零要分别处理。

5. Indexer 数据字典

下面“整数串”均指十进制 string；? 表示允许 null，而不是保证从 JSON 中省略。

5.1 公共活动和资金记录

充值 requestedAmount/receivedAmount 是原始币数量，wusdCredited 是账本入账；提现 wusdDebited 是账本扣款，tokenAmount 是外部币数量。两种余额不要相加作为同一个账户余额。

5.2 Lotto3dRound / Lotto3dTicketHistory

3D 号码范围 0～999，展示补足三位。未开奖的 null 不能渲染成确定的 000。roundTicketPrice 当前固定 null，历史记录本身不提供真实票价快照。

5.3 UmaRound / UmaRoundHistory

UmaRoundHistory 另有 status:string、sales:整数串、betCloseTime:整数串、prizePool:整数串?。历史奖池在存在结算时为各奖级 payout × winUnits 之和加 carryNext；无结算为 null，并非简单取销售额 80%。

B03/I20 的 effectiveStatus 可为：upcoming / betting_open / sales_close_overdue / awaiting_assertion / assertion_overdue / challenge_window / resolution_pending / disputed / ready_for_retry / awaiting_settlement / settled / cancelled。

这些是展示状态字符串，不是 Solidity 枚举数字。断言成立、开奖号码确定、奖金结算已发布分别是不同阶段。

5.4 UmaTicket / UmaTicketHistory / UmaSettlement / UmaDrawRequest

UmaDrawRequest.status 为 Pending / ResolutionPending / Disputed / Abandoned / Resolved。World Lotto 号码 0～9999999，显示补足七位。Ticket/DrawRequest 的 number/winningNumber 在 Indexer 是字符串，而 Round 的 winningNumber 是 number/null，不要混用类型。

注意：当前 UmaSettlement REST 响应没有 claimDeadline 字段，虽然前端 mapSettlement 会读取并默认成 0。真正的领奖截止时间要从 UmaRound.claimDeadline 读取，不能将映射默认值当成服务端返回。

6. Next.js 接口与服务端上游

N01 每项 candle 为 {time,open,high,low,close,volume}，均为 number，time 是毫秒。symbol 为 BTC/USD，interval 为 5m。优先请求配置的 Chainlink K 线 URL，成功但无有效数据或非成功 HTTP 时可继续用 Binance /api/v3/klines?symbol=BTCUSDT&interval=5m&limit=60。Chainlink fetch 直接抛异常时进入外层 503，不保证所有错误都会回退。

来源分别为 chainlink-candlestick 或 display-fallback-binance-btcusdt；Binance 只是显示兜底，不是协议最终结算来源。服务端内存缓存5秒，响应 public,max-age=5,stale-while-revalidate=15。

N02 服务端先 GET ${MARKET_SERVICE_URL}/v1/markets，选当前时间范围内 Open 市场，再 GET /v1/markets/:marketId/quote?tokenId=...。有效 quote 字段由上游透传，页面使用 bestBid:number|null、bestAsk:number|null、lastTrade:{price?:string}|null。接口未声明稳定的完整 quote DTO，调用方不能假定除此之外的字段永远存在。

无市场返回 {outcome,price:null,source:"wf-matcher",status:"unavailable"}；异常响应另加 error。即使 HTTP 200，也必须看 status，不能直接认定有报价。

重要：BtcMarketData 当前在页面可见时每秒请求一次 K 线和 yes/no 两次报价，active=false 不停止请求。停用 Market 服务不代表浏览 BTC 页时不会调用这些接口。/btc15m 仅重定向到 /btc5m，没有独立 15M API。

7. RPC、钱包与链上接口

7.1 传输与交易确认

只读客户端使用配置的 RPC URL，支持 HTTP batch；Polygon 可经 Multicall3 合并读取。交易由用户连接的钱包处理，钱包可能使用自己的广播节点，不能保证写交易一定经过应用的只读 RPC。

交易过程：读取 nonce/准备 calldata → eth_call 预执行和钱包网络检查 → 用户确认 → 钱包返回 hash → 每2秒轮询回执。等待超时/查询失败后继续查询原 hash，不自动重发付款。仅加速(repriced)交易继续跟踪；取消或其他替换会提示核对钱包记录。同账号在本页面运行时串行处理，不能防止另一个标签页或外部客户端同时用 nonce。

7.2 链上只读方法

paused/ticketPrice/currentCarryPool/accumulatedPool/requiredBond 等在本方案由 BFF 服务端读取，不是浏览器额外逐个调合约。余额日常来自 I02，显式刷新会读链并更新本地查询缓存。

7.3 充值写方法

先调用 ERC-20 approve(address Reserve,uint256 amount)（标准返回 bool），仅当 allowance 不足时执行，当前授权的是本次 amount，不是无限额度。成功后调用：

StablecoinReserve.deposit(token, amount, authorizedAmount, minWusdOut, deadline, nonce, signature)

合约 Solidity 返回 (received,wusdCredited)；真实钱包发送接口先返回 tx hash，不直接返回 Solidity return value。最终入账参考链上 Deposited 事件和账本余额。

当前 minWusdOut=amount 依赖现有同精度、1:1资产配置；支持不同 decimals 或兑换率时不能照抄这个填法，应使用实际 WUSD 预估。文档记录现状，不声称前端已泛化所有代币。

授权 EIP-712 domain：name=WUSDStablecoinReserve，version=1，chainId=当前部署，verifyingContract=Reserve。类型 DepositAuthorization 字段严格按 user:address,token:address,authorizedAmount:uint256,deadline:uint256,nonce:uint256 排列。签名者是服务端，不是充值用户再签一次 typed data。

7.4 购票写方法

当前前端调用 UnifiedLedgerV4.executePurchaseV4(request,purchaseData)，Solidity 返回 receiptId(bytes32)，钱包返回 tx hash。调用者钱包必须对应 request.owner。

当前 Lotto3D 和 World Lotto 购票面板未传 partnerCode/wfOrderId，因此默认都是 zeroHash，不会自动从网址解析渠道码。第三方协议支持的归因能力与本官网默认购买参数需要区分。

purchaseData 采用标准 ABI 编码，不是 packed：

roundId 在 purchaseData 中，不是 request 元组独立字段。request 不包含 allocationVersion/partnerBps；它们由链上轮次配置决定。后台查询响应里仍有这些字段作为核算记录，不意味着用户要在购票时提交。

当前钱包模式不调用 executePurchaseWithAuthorizationV4、不申请 session key、不调用 Relayer，也没有每次购票的独立 EIP-712 签名步骤。用户每笔购买仍要确认一笔钱包交易并支付 Gas；登录一次不能替代每笔交易确认。

7.5 领奖/退款

不是向 Backend 提交领奖申请。成功奖金进入 WUSD 账本，提到外部钱包另走提现。World Lotto/3D 虽可从索引看到 refunded 状态，本次搜索未发现页面主动调用其退款合约函数；不能将“有退款索引”写成“已有完整退款按钮”。

7.6 提现写方法

StablecoinReserve.withdraw(token,wusdAmount,minTokenOut,recipient)

前端检查账本余额、储备币余额和收款地址，调用 previewWithdraw 和 simulateContract，然后钱包发交易。无需另一次 ERC-20 approve，无提现 HTTP 授权接口。成功后账本扣款，Reserve 向 recipient 转币；仍受调用者余额、储备、授权、签名、minOut 和暂停约束；新 Reserve 无单笔或每日数量上限，废弃限额槽的 0 不代表禁止操作。Solidity 返回 uint256 tokenAmount，发送交易的前端仍先拿到 hash，通过回执和事件核实结果。

7.7 代码保留的 RPC 网关

只有 RPC URL 选到 Backend 时才使用 POST /api/v1/rpc。请求为标准 {jsonrpc:"2.0",id,method,params} 或1～50项数组。返回 result 或 {error:{code,message,data?}}；RPC 方法错误可以是 HTTP 200，必须检查 JSON error。

该网关按配置限流，非法空/超50项 batch 返回400，超限429。服务方法白名单为只读/估算类（包括 eth_call、eth_getTransactionReceipt、eth_estimateGas 等），不支持用它代替钱包广播 eth_sendRawTransaction。本节只记录仓库仍存在的实现，不建议改变当前直连部署要求。

8. 用户完整调用路径

9. 刷新、边界与接入注意事项

接入方需要特别区分：

• 登录成功、取得充值授权、钱包返回Hash、链上成功、Indexer出现记录、奖金结算完成是不同状态。
• “没有轮次”是合法空数据；接口错误不能伪装成余额为0或开奖结果为0。
• B03/I01等有 deploymentId，不是所有REST响应都包含该字段；上线需统一前后端/Indexer的部署配置，不能凭某个地址字段判断完全一致。
• 公共查询不要求 Partner API Key，Partner Console 则要求绑定钱包成员身份；公开归因码不能代替身份鉴权。
• Web2佣金份额由后台规则计算，前端既不提交最终返佣额，也不通过改写购票参数决定它。
• 当前查询带数量上限；完整财务历史导出不能直接使用页面已加载数组。

10. 不属于当前页面调用的接口

Backend bridge、管理后台/Safe审核、内部 Settlement任务、Indexer GraphQL/SQL以及 Indexer /v1/protocol/purchases/... 等更广泛协议接口，不在本前端运行时调用链中；本清单不将它们列为前端依赖。

没有发现当前页面通过业务 WebSocket、SSE 或 webhook 接收订单/返佣结果的实现。WalletConnect 的内部连接服务是钱包组件依赖，不是项目的订单 webhook。

没有新增或恢复 Partner API Key、Partner Order API、提交 txHash 接口；前端本地保存 hash 用于等待原交易回执，不等于要求第三方上报 hash。