billing.allowance

Build an unsigned sui::allowance grant for auto top-up.

Details

Endpoint: POST /v1/billing/allowance
Credits: Free
Rate class: Light. Counts against your light requests per second.

Returns transaction bytes that grant tide's spender a sui::allowance over your USDC address balance: at most `maxTotalUsd` in all, at most `perDrawUsd` per `windowHours` (enforced on chain), ending at `expiresDays`. When your credits left fall under `thresholdCredits`, tide draws `perDrawUsd` into the treasury (tide pays the gas) and credits your account. Allowances spend only from the address balance, so `depositUsd` first moves USDC coin objects there (default: the per-draw amount if your address balance is short). Sign and send it with your wallet (it pays a little SUI gas), then call /v1/billing/allowance/confirm with the digest. Revoke on chain any time.

Parameters

Name	Type	Description
maxTotalUsdrequired	string or number	The most tide may ever draw, USD.
perDrawUsdrequired	string or number	USD per draw, and the most tide may draw per window.
windowHours	integer	The rate-limit window, 1 to 720 hours. Default 1.
expiresDays	integer	Days until the allowance ends, 1 to 730. Default 90.
thresholdCredits	integer	Draw when credits left fall under this. Default: what one draw buys.
depositUsd	string or number	USD of USDC coins to move into your address balance in the same transaction. 0 for none.
address	string	The funder, when you call without a key.

Request

Send your key in the x-api-key header, or leave it out to use the keyless tier.

curl

curl -X POST "https://api.tide.ad/v1/billing/allowance" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "maxTotalUsd": "100",
  "perDrawUsd": "10",
  "windowHours": 1,
  "expiresDays": 90
}'

TypeScript

const res = await fetch("https://api.tide.ad/v1/billing/allowance", {
  method: "POST",
  headers: {
    "x-api-key": process.env.TIDE_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "maxTotalUsd": "100",
    "perDrawUsd": "10",
    "windowHours": 1,
    "expiresDays": 90
  }),
});
const data = await res.json();

Response

JSON

{
  "txBytes": "AAAC...",
  "gasless": false,
  "spender": "0x31c964fd011762b6e1c1cd38737369de1d4bdd07d4a9a0f0baf3b96c4e135f0e",
  "terms": {
    "maxTotalUsd": "100",
    "perDrawUsd": "10",
    "windowHours": 1,
    "expiresAt": "2027-02-02T00:00:00.000Z",
    "thresholdCredits": 3333333
  }
}