0 active

DOCS /GRANTS & POLICY API

Grants & policy API

The REST surface behind the SDK. Every route accepts your browser session (SIWE) or Authorization: Bearer yf_… — the key you minted at dashboard/keys. Keys authenticate as your wallet; grants stay owner-scoped either way.

Grants

A grant is your agent's expense account — an allowlist plus per-call/per-day/lifetime caps. CRUD it here, sign the terms with your wallet (EIP-712), and sync receipts into the hosted ledger.

  • GET/api/grants

    List your grants with spend totals

  • POST/api/grants

    Create a grant (allowlist + caps + expiry)

  • GET/api/grants/:id

    One grant + recent ledger + budget status

  • PATCH/api/grants/:id

    Adjust caps/label, revoke or reactivate

  • DELETE/api/grants/:id

    Delete a grant (ledger cascades)

  • GET/api/grants/:id/signature

    EIP-712 payload to wallet-sign the terms

  • PUT/api/grants/:id/signature

    Attach the signature (server-verified)

  • POST/api/grants/:id/ledger

    Sync a receipt into the hosted ledger

The pre-flight: GET /api/agent/policy

One Bearer-only endpoint answers the SDK's standing question — "may I still pay, and how much?" — with the key's budget and the owner's grant in a single response. The SDK loads it at startup and refuses with GrantError('OVER_AGENT_BUDGET') once the key is over budget.

GET /api/agent/policy
Authorization: Bearer yf_…

{
  "agent": {
    "keyId": "cmq…", "label": "travel-agent",
    "perDayUsd": 5, "spentTodayUsd": 1.23,
    "remainingTodayUsd": 3.77, "overBudget": false
  },
  "grant": { "allow": […], "perCallUsd": 0.05, … }
}

The full response shape, the kill-switch halted/haltReason fields, and how budgets are enforced live on Agents & budgets.

Receipt sync body

The SDK's onReceipt seam POSTs to /api/grants/:id/ledger automatically when you pass apiKey (see ledger sync). The body fields, if you'd rather wire it yourself:

  • hoststring

    Hostname or full URL of the paid endpoint (required)

  • amountUsdnumber

    USD settled — 0 for denials (required)

  • okboolean

    true = settled, false = denied/failed (default true)

  • txHashstring

    Base settlement transaction, when settled

  • serviceNamestring

    Display name for the dashboard charts

  • notestring

    "settled", a violation code, or your own marker