boxSpendCap
Sets, raises, lowers or clears the box's daily spend cap: the most units its watch hits may draw in a UTC day.
Cost: Free. Signed by the box's agent over method
POST, path/agent/v1/<address lowercased>/box/spend-capand the body{"maxUnitsPerDay": ...}: the whole number, ornullto clear the cap. Or send anARCGATE-KEYof the account the box is linked to, with no signature. Another account's key, or any key for a box that is not linked, does not apply to the box: the call is checked as if no key were sent, so it needs the signature. A key nobody holds is a 401key_invalid. The key keeps working after the account has lapsed (its grace has ended).Inputs:
address(path), any letter case, and the body{maxUnitsPerDay}, a whole number of at least 1, ornullto clear the cap. Leaving it out is a 400, never a clear. A box has no cap until it sets one.Returns:
addressandmaxUnitsPerDay, the cap now (null: none).boxStatusshows it too.The cap: it counts the units the box's watch hits draw in a UTC day, from its own balance or, when the box is linked to an account, from the account. It is not counted before
agent.units.cutoverfor an unlinked box, whose hits spend the allowance. An inbound post and a notice draw no units and are never limited by it. A hit whose units would take the day past the cap is refused whole: it is not stored, nothing is drawn, and it is counted inunstoredWatchHits. Keyed lookups pass through no box and are never limited by it.At the cap: the box's watches pause (
statepaused_daily_capinwatchList) and arcgate stores onenoticemessage with eventpaused_daily_cap,maxUnitsPerDay,sinceandresumesAt. The notice follows each channel's filter. The watches resume with a fresh baseline at the next UTC day, or when the cap is cleared or raised above the units drawn that day: a condition that became true during the pause fires at the next change, and one that had already fired does not fire again. A cap lowered under the day's count pauses the box at its next hit. The box's balance is not touched by the cap.Errors:
400
invalid_request:maxUnitsPerDayis missing, is not a whole number from 1 or null, or the body has another field.404
box_not_found: the address has no box. Create one first (boxCreate).
Next:
boxStatus: read the cap.watchList: see whether the watches are paused.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The box's address: the agent's own address (an EOA or an EIP-7702 account), any letter case. The box is keyed by it, and a signed request must be signed by it. | |
| agentSignature | No | The agent's EIP-712 signature over this request, as the AGENT-SIGNATURE, AGENT-NONCE and AGENT-EXPIRY headers carry it over HTTP. Sign the typed data `AgentRequest` with fields `address` (the box), `method`, `path`, `bodyHash`, `nonce` and `expiry`, under the domain {name: "arcgate", version: "1"} with no chainId (a wallet that can only sign with one, such as Circle's, may add the chainId of the chain this deployment serves, 5042 on Arc mainnet, and no other). The `path` is the request path with every parameter filled in and the address lowercased. The `bodyHash` is the keccak256 of the canonical JSON of the body you send (sorted keys, no whitespace), or of no bytes when there is none. Omitting it is a 401 signature_required unless an ARCGATE-KEY of the account the box is linked to is sent (over MCP, on the connection), and it is never a charge: the call is free. | |
| maxUnitsPerDay | Yes | The most units the box's watch hits may draw in a UTC day, a whole number from 1, or null to clear the cap. Required: leaving it out is a 400, never a clear. |