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 'x-auth-token: Bearer $TOKEN' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -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: {
    "x-auth-token": "Bearer $TOKEN",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "asset": "USDT",
    "amount": "500.000000"
  }),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/sandbox/faucet",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "asset": "USDT",
      "amount": "500.000000"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zise.com/v1/sandbox/faucet",
    strings.NewReader(`{
  "asset": "USDT",
  "amount": "500.000000"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/sandbox/faucet"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "asset": "USDT",
  "amount": "500.000000"
}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double
$ch = curl_init('https://api.zise.com/v1/sandbox/faucet');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "asset": "USDT",
  "amount": "500.000000"
}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval
200 
{
  "ok": true,
  "asset": "USDT",
  "credited": "500.000000",
  "ledger_scale": 6,
  "journal_id": "jrn_01J8Z6M2K9QF3H7V0"
}