Wallet API /api/wallet

Credit balance, transactions and usage history. All endpoints require a session token.

GET /api/wallet

Returns the balance, the 50 most recent transactions and available top-up packs.

{
  "ok": true,
  "credits": 992,
  "transactions": [
    { "id": "88", "delta": -8, "balanceAfter": 992, "reason": "调用 nano-banana-2", "model": "nano-banana-2", "createdAt": "..." }
  ],
  "packs": { "5": 1000, "20": 4200, "50": 10750 },
  "sandbox": true
}

Each transaction includes balanceAfter, the balance after posting. This allows you to reconcile users.credits against the transaction ledger.

POST /api/wallet/topup

Adds credits. The request's amount is the pack price in USD, not the number of credits.

Packs are configured by the platform and may change. Use the packs returned by GET /api/wallet as the source of truth. The Chinese reference lists these packs:

Pack (USD)	Credits
5	1000
20	4200
50	10750

curl -X POST "https://modelfold.ai/api/wallet/topup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":5}'

{ "ok": true, "credits": 1992, "sandbox": true }

Sandbox top-up behavior in this reference

The examples above describe the sandbox endpoint in the Chinese reference. A response with sandbox: true means credits are added directly, without a payment provider or a real charge. In a payment-enabled deployment, top-ups follow an order → payment → callback crediting flow. Use the console's current checkout flow for real payments.

An amount outside the pack table returns 400 invalid_pack.

GET /api/wallet/usage

Returns the 100 most recent model requests.

{
  "ok": true,
  "requests": [
    { "id": "310", "model": "nano-banana-2", "endpoint": "images", "status": "ok", "credits": 8, "latencyMs": 4310, "error": "", "createdAt": "..." }
  ]
}

Field	Description
status	ok / failed / rejected
credits	Credits charged for a successful call; 0 for a failed or rejected call
error	Failure reason, such as insufficient_credits or upstream_failed

Billing rules

• Insufficient balance returns 402, without a provider call or a ledger entry.
• Failed provider calls are refunded automatically and recorded with status failed.
• Chat requests are settled against actual token usage. Differences from the reservation are refunded or charged automatically.

See Pricing for complete billing rules.