Mandates
The permission a user signs that lets your server wallet charge them, within limits, until a date - and optionally see their balance.
A mandate is the user's own signed permission, recorded on USD Network, for one of your server wallets to charge their account. The network enforces its limits on every charge; you can't go over them and neither can anyone holding your server key.
What a mandate holds
| Field | Meaning |
|---|---|
spender | The server wallet allowed to charge |
perTx | Most one charge can take |
daily | Most all charges can take in one UTC day |
total | Most it can ever take; "0" means no lifetime limit |
until | When it ends (ms since 1970), at most 400 days ahead |
read | Whether that server wallet may read the account's balance and the payments between them |
partner | Your partner id, so the user's wallet shows your name |
Rules: perTx ≤ daily, and daily ≤ total when there is a total. An account can hold up to 50 mandates, one per spender; a new one for the same spender replaces the old and starts its counters again.
How users give one
With USD.NET Connect: USDNet.connect({ partner, mandate: { … } }). The user sees, for example:
Wallets and scripts can also sign one directly (POST /mandate, the mandate message).
Check one
const m = await usd.mandate(user); // null if none, or revoked
// { spender, perTx: "25", daily: "100", total: "500", until, read: true,
// spent: "4.99", dayUsed: "4.99", leftToday: "95.01", leftTotal: "495.01", charges: 1, active: true }GET /mandate/:owner/:spender, signed by either side (x-usd-read). Your server wallet's read pass works for every mandate that names it, with or without read.
When it ends
- The user presses Revoke in Settings → Connected apps: a
revoketransaction, final at once. You getmandate.revoked. untilpasses.- You remove the server wallet from your partner record, or pause the record.
After that, charges answer 403 and, if it had read, reads of the account return nothing.
Reading a user's account
With read: true, your server wallet can read:
const u = await usd.user(user);
// { address, grant: true, balance: "95.01", frozen: false, mandate: { … }, transactions: [ only those between them and you ] }…and their deposit addresses on other chains. It never sees anything else in their account: other payments, other businesses, other balances.
Good practice
- Ask for what you need. A pack shop with packs at 4.99 asks for maybe 25 per charge and 100 a day, not 10,000.
- Show users what they've allowed and link to
usd.net/wallet/settingsto revoke. - When a charge fails with
403because a limit is reached, ask the user to connect again with new limits.