Account & wallets

Fund company wallets with Stripe Checkout, create wallets with a budget (rill_vw_*), manage fleet policy, and open the billing portal. Owner JWT for account wallets and create; wallet key for allowance status.

Same flow in MCP: rill_create_wallet

Auth

Create wallet, list accounts, revoke, rotate, and billing portal need an owner Supabase JWT. Send X-Rill-Environment: live|test (default live) on owner JWT calls — Test mode uses a separate wallet balance and mints rill_vw_test_* / rill_sk_test_* keys. Fund-checkout accepts an owner JWT or a rill_vw_* key (VW may only fund its own account wallet; agents prefer POST /agent/fund-checkout). Wallet status uses Authorization: Bearer rill_vw_*. Send Idempotency-Key on fund-checkout, mock fund, and other mutating writes.

Authorization: Bearer <owner JWT or rill_vw_*>

Featured endpoints

Fund with Stripe Checkout

POST /accounts/:id/fund-checkout

Create a top-up PaymentIntent for the dashboard Payment Element (default), or pass hosted=true for a Stripe Checkout URL. Response includes amount (wallet credit), processing_fee, total_charged, and either client_secret (+ publishable_key) or checkout_url. Wallet credits face amount; human pays total. Poll GET /funding/:id until paid, then create wallets.

Parameter	Type	Required	Description
`id`	path	yes	Account wallet id (from claim or GET /accounts)
`amount`	number	yes	USD wallet credit (decimal dollars). Card processing is added on Checkout.

Request body

body

{
  "amount": 25
}

What to save

Save funding_intent_id. Dashboard uses client_secret in-modal; agents that need a link should pass hosted=true and send checkout_url. Poll the funding intent until paid before expecting Spend to succeed.

Agents: POST /agent/fund-checkout with a rill_vw_* key (always hosted Checkout URL).
Local or non-production may allow POST /accounts/:id/fund (mock) when Stripe is unset, mock credits face amount with no card fee.
MCP twin: rill_fund with action=checkout, then action=intent.

Create a wallet

POST /wallets

Create a wallet with a budget from a funded account wallet. Set period allowance and max per transaction in USD. Optional allowlist and policy_template_id apply fleet defaults for many agents sharing one template.

Parameter	Type	Required	Description
`account_wallet_id`	string	yes	Funded account wallet that backs this wallet
`agent_slug`	string	yes	Agent slug (3–30 chars); forms the agent FQDN
`period_allowance`	number	yes	USD period budget for the wallet
`max_transaction`	number	yes	USD max per individual pay
`allowlist`	string[]	no	Optional host/URL allowlist for pays on the web
`policy_template_id`	string	no	Fleet template; overrides allowance fields when set

Request body

body

{
  "account_wallet_id": "…",
  "agent_slug": "research",
  "period_allowance": 50,
  "max_transaction": 5
}

What to save

Save the rill_vw_* key immediately, it is shown once. Use it for POST /spend/pay-url and POST /pay. Store the wallet id for revoke/rotate.

Fund the account wallet before creating a wallet or pays fail with insufficient balance.
MCP twin: rill_create_wallet.

Read wallet allowance

GET /wallets/me/status

Return remaining period allowance and per-tx caps for the calling wallet. Call after pays to stay inside budget. Seller balance is a different route (GET /sellers/me/balance).

What to save

Use remaining allowance and max_transaction from the response to decide whether to pay, wait for period reset, or create a wallet with a higher budget.

Auth with the wallet key (Bearer rill_vw_*).
MCP twin: rill_balance with vw_key.

All endpoints

GET/accountsList owner wallets
GET/accounts/mePrimary wallet
GET/accounts/:idWallet by id
POST/accountsCreate wallet
POST/accounts/:id/fund-checkoutStripe top-up (Idempotency-Key)
POST/accounts/:id/fundMock fund when allowed
GET/accounts/:id/spend-attemptsOpen-rail MPP/x402 spend history (owner)
POST/accounts/me/billing-portalStripe Customer Portal
GET/funding/:idPoll Checkout status
GET/walletsList VW keys
POST/walletsMint VW (optional policy_template_id)
GET/wallets/:idVW by id
GET/wallets/me/statusAllowance remaining (VW key)
GET/wallets/:id/statusStatus by id
POST/wallets/:id/revokeRevoke VW
POST/wallets/:id/rotateRotate VW secret
GET/ledgerLedger lines
GET/receiptsReceipts

Usage notes

Revoke or rotate a wallet with POST /wallets/:id/revoke|rotate when a key leaks.
Fleet defaults: create a policy template, then pass policy_template_id when creating a wallet.
Spend happy path: claim → fund-checkout → create wallet → pay Accept link (seed_gate) or payment_ready URL via POST /spend/pay-url.

Auth

Authorization: Bearer <owner JWT or rill_vw_*>

Featured endpoints

Fund with Stripe Checkout

POST /accounts/:id/fund-checkout

Parameter	Type	Required	Description
`id`	path	yes	Account wallet id (from claim or GET /accounts)
`amount`	number	yes	USD wallet credit (decimal dollars). Card processing is added on Checkout.

Request body

body

{
  "amount": 25
}

What to save

Agents: POST /agent/fund-checkout with a rill_vw_* key (always hosted Checkout URL).
Local or non-production may allow POST /accounts/:id/fund (mock) when Stripe is unset, mock credits face amount with no card fee.
MCP twin: rill_fund with action=checkout, then action=intent.

Create a wallet

POST /wallets

Parameter	Type	Required	Description
`account_wallet_id`	string	yes	Funded account wallet that backs this wallet
`agent_slug`	string	yes	Agent slug (3–30 chars); forms the agent FQDN
`period_allowance`	number	yes	USD period budget for the wallet
`max_transaction`	number	yes	USD max per individual pay
`allowlist`	string[]	no	Optional host/URL allowlist for pays on the web
`policy_template_id`	string	no	Fleet template; overrides allowance fields when set

Request body

body

{
  "account_wallet_id": "…",
  "agent_slug": "research",
  "period_allowance": 50,
  "max_transaction": 5
}

What to save

Save the rill_vw_* key immediately, it is shown once. Use it for POST /spend/pay-url and POST /pay. Store the wallet id for revoke/rotate.

Fund the account wallet before creating a wallet or pays fail with insufficient balance.
MCP twin: rill_create_wallet.

Read wallet allowance

GET /wallets/me/status

Return remaining period allowance and per-tx caps for the calling wallet. Call after pays to stay inside budget. Seller balance is a different route (GET /sellers/me/balance).

What to save

Use remaining allowance and max_transaction from the response to decide whether to pay, wait for period reset, or create a wallet with a higher budget.

Auth with the wallet key (Bearer rill_vw_*).
MCP twin: rill_balance with vw_key.

All endpoints

GET/accountsList owner wallets
GET/accounts/mePrimary wallet
GET/accounts/:idWallet by id
POST/accountsCreate wallet
POST/accounts/:id/fund-checkoutStripe top-up (Idempotency-Key)
POST/accounts/:id/fundMock fund when allowed
GET/accounts/:id/spend-attemptsOpen-rail MPP/x402 spend history (owner)
POST/accounts/me/billing-portalStripe Customer Portal
GET/funding/:idPoll Checkout status
GET/walletsList VW keys
POST/walletsMint VW (optional policy_template_id)
GET/wallets/:idVW by id
GET/wallets/me/statusAllowance remaining (VW key)
GET/wallets/:id/statusStatus by id
POST/wallets/:id/revokeRevoke VW
POST/wallets/:id/rotateRotate VW secret
GET/ledgerLedger lines
GET/receiptsReceipts

Usage notes

Revoke or rotate a wallet with POST /wallets/:id/revoke|rotate when a key leaks.
Fleet defaults: create a policy template, then pass policy_template_id when creating a wallet.
Spend happy path: claim → fund-checkout → create wallet → pay Accept link (seed_gate) or payment_ready URL via POST /spend/pay-url.