跳转到主要内容

​
概览

  • 基础路径：/api/v1
  • 认证：通过 x-api-key 传递 API Key
  • 幂等：写入端点需要 Idempotency-Key（UUID）
  • 响应格式：所有响应包含 x-request-id 用于追踪

​
端点

  • GET /api/v1/wallets – 列出用户钱包
  • GET /api/v1/wallets/balances – 调用方钱包余额（按链；默认使用默认钱包）
  • GET /api/v1/wallets/:address/balances – 查询特定所属钱包地址余额
  • GET /api/v1/tx/:id – 获取交易详情
  • POST /api/v1/send – 发送原生资产与代币（EVM + Solana）
  • POST /api/v1/token/approve – ERC20 授权（仅 EVM）
  • POST /api/v1/contracts/send – 通用合约交互（仅 EVM）
  • POST /api/v1/trade/quote – 获取兑换报价（EVM + Solana）
  • POST /api/v1/trade/swap – 执行兑换（EVM + Solana）

​
链

完整列表见「支持的链」。在请求的 chain 字段中使用链标识（例如 base、solana-devnet）。

​
频率限制

  • 写入（包括 POST /api/v1/trade/quote）：每用户每分钟 15 次请求
  • 读取：每用户每分钟 60 次请求
  • 响应：超限返回 HTTP 429
  • 响应头：Retry-After（距离下一窗口的秒数）

​
幂等（写入）

  • 所有变更类端点需要 Idempotency-Key。
  • 重复使用相同请求体与 Key 会返回原始 200 响应。
  • 若请求体不同，返回 HTTP 409 且 code: IDEMPOTENT_BODY_MISMATCH。
  • 若没有存储的成功响应，返回 HTTP 409 且 code: IDEMPOTENT_REPLAY。
  • Key 以用户为作用域；端点路径会记录用于追踪。
  • 适用范围：POST /api/v1/send、POST /api/v1/token/approve、POST /api/v1/contracts/send、POST /api/v1/trade/swap。

​
错误处理

​
错误响应格式

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
错误代码

  • UNAUTHORIZED – 缺少/无效认证或 API 密钥（HTTP 401）
  • FORBIDDEN – 已认证但无权限执行操作（HTTP 403）
  • NOT_FOUND – 资源未找到（HTTP 404）
  • RATE_LIMITED – 超过频率限制（HTTP 429）
  • INVALID_INPUT – 无效请求参数（HTTP 400）
  • WALLET_NOT_FOUND – 指定钱包未找到
  • USER_NOT_LINKED – 用户未链接到 Privy
  • WALLET_NOT_DELEGATED – 钱包未委托给服务器签名者
  • WALLET_ID_REQUIRED – 缺少 Privy 钱包 ID
  • CHAIN_UNKNOWN – 未知或不支持的链
  • INSUFFICIENT_FUNDS – 发送方缺少资金用于支付价值/费用
  • IDEMPOTENT_BODY_MISMATCH – 相同幂等键但请求体不同（HTTP 409）
  • IDEMPOTENT_REPLAY – 幂等键已被使用（HTTP 409）
  • PRIVY_RPC_ERROR – Privy RPC 服务错误
  • SEND_FAILED – 交易提交失败
  • SERVICE_UNAVAILABLE – 所需服务未配置
  • QUOTE_FAILED – 报价服务错误（HTTP 400）
  • INTERNAL_ERROR – 服务器错误
QUOTE_FAILED 细节：
  • Solana/Jupiter：某些 Solana mint 在 Jupiter 上不可交易（经筛选的白名单）。这种情况下，此 API 返回 HTTP 400，code: QUOTE_FAILED，错误消息如：“Token not tradable on Jupiter”。
  • EVM/1inch：如果代币不被 1inch 支持，API 返回 HTTP 400，code: QUOTE_FAILED，消息如：“Token not tradable on 1inch”。
  • 当请求的输出代币/mint 被上游提供商标记为不可交易时，这是预期行为，即使其他地方存在流动性池。

​
校验

​
地址格式

  • EVM: must match /^0x[a-fA-F0-9]{40}$/
  • Solana: must be a valid base58 public key

​
通用参数

  • 数量（EVM）：仅整数字符串（十进制或 0x-hex）。必须非负。对于 ERC20 和 value，必须适配 uint256。
  • 数量（Solana）：基本单位的整数字符串。SPL 数量必须适配无符号 64 位范围。
  • 发送方（from）：可选。如省略，使用用户针对指定链的默认钱包。
  • 幂等：所有写入端点需要 Idempotency-Key 头。相同请求体的重复请求返回原始响应。

​
原生代币关键字

交易端点（/api/v1/trade/quote、/api/v1/trade/swap）接受不区分大小写的 NATIVE 关键字用于 fromToken/toToken：
  • EVM：NATIVE 解析为 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana：NATIVE 解析为包装的 SOL mint So11111111111111111111111111111111111111112
  • 响应返回解析后的地址（而非 NATIVE）
  • 发送端点使用 asset: "native" 而不是代币地址来进行原生转账

​
约定

  • 链选择：使用 chain 标识（如 base、base-sepolia、solana-devnet）。
  • Solana Transaction.chainId 哨兵映射：0 = 主网，-2 = 测试网，-3 = 开发网。
  • 幂等：对每位用户与 Key 唯一；重复请求返回原始响应；请求体不一致 → 409。

​
相关

支持的链

策略与安全