Z Zise Developers
/
API 参考 › 沙盒
POST /v1/sandbox/faucet

沙盒 · 给你的沙盒预付账户补钱

Scope merchant:read 商户自身 需 x-idempotency-key 动钱 · 增商户预付 available（对手方 custody.settled）
这个端点会动钱

失败处置见下方响应表。超时（504）用同一把幂等键重试——我方可能已经处理完；业务失败要换新键，同键会原样返回那次失败。

只在沙盒环境存在；用 live 凭据调它返回 404（不是 403 —— 在生产上

这个能力根本不该存在）。判据是本次令牌解析到的商户是不是影子主体，

不是你打的域名。

它走的是与生产逐字相同的入账路径，所以沙盒里的资金闸、排队、

低水位、账本不变量全都会被真的跑到。凭空改余额的接口验不出这些。

入参 amount 与出参 credited 是十进制串（如 "500.000000"），

与 /v1/merchant/balances 的定点整数串不是一个形状。

缺省充 10000（该资产的整数单位），单次上限 100 万单位 ——

一个能一次充 10^30 的接口会让你在沙盒里跑出一组与生产完全不同的

限额行为。

幂等：同一把 x-idempotency-key 重放拿回同一笔，且带

duplicated: true。这一档下没有真的入账，别把它当成第二次到账。

前置条件

  • 本次令牌解析到的是沙盒影子主体（live 凭据一律 404）
  • 资产在 assets 里且已启用
字段类型必填说明
x-idempotency-key string 必填 UUID v4。缺了回 idempotency_key_required，格式不对回 idempotency_key_invalid；同键异体回 idempotency_key_reused。

请求体

字段类型必填说明
asset string 必填 资产代码，大小写不敏感（服务端转大写）。认不出回 asset_not_allowed
amount string 可选 充多少。十进制字符串，小数位不得超过该资产 ledger_scale（超出的尾数全为 0 时放行）。 省略则按 10000 个整数单位。必须为正。USDT（scale 6）："500.000000"

响应

200已入账（duplicated: true 时表示幂等命中，本次没有真的入账）
{
  "ok": true,
  "asset": "USDT",
  "credited": "500.000000",
  "ledger_scale": 6,
  "journal_id": "jrn_01J8Z6M2K9QF3H7V0"
}
400invalid_request body 不是 JSON / 缺 asset / 金额非法或非正 · asset_not_allowed 资产不在目录或已停用 · limit_exceeded 单次超过 100 万个整数单位（带 limit_type: single）
404不在沙盒环境
409idempotency_key_reused 同键不同 body · idempotency_in_progress 首次请求还在处理中
调用样例 
curl -X POST 'https://api.zise.com/v1/sandbox/faucet' \
  -H 'authorization: Bearer $TOKEN' \
  -H 'x-zise-merchant: $MERCHANT_ID' \
  -H 'x-idempotency-key: $(uuidgen)' \
  -H 'content-type: application/json' \
  -d '{
    "asset": "USDT",
    "amount": "500.000000"
  }'
const res = await fetch(
  "https://api.zise.com/v1/sandbox/faucet",
  {
    method: "POST",
    headers: {
      "authorization": "Bearer $TOKEN",
      "x-zise-merchant": "MERCHANT_ID",
      "x-idempotency-key": "crypto.randomUUID()",
      "content-type": "application/json"
    },
    body: JSON.stringify({
      "asset": "USDT",
      "amount": "500.000000"
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/sandbox/faucet",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-idempotency-key": "$(uuidgen)",
        "content-type": "application/json"
    },
    json={
        "asset": "USDT",
        "amount": "500.000000"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()