Financial OS

The Financial OS combines treasury banking, capital financing, card issuing, and autonomous AI agent wallets on a double-entry ledger. These endpoints cover ledger-backed wallets, credit lines, virtual cards, and programmable agent wallets.

Authentication

All Financial OS endpoints require a valid JWT or API key. Treasury and agent wallets are owned by the authenticated user.

Endpoints

POST/walletsCreate a ledger-backed treasury wallet

GET/wallets/meGet the authenticated user's treasury wallet

GET/wallets/:idGet a treasury wallet

GET/wallets/:id/ledgerGet double-entry ledger history

POST/merchants/:merchantId/capital/credit-linesCreate a credit line

GET/merchants/:merchantId/capital/credit-linesList credit lines

POST/wallets/:walletId/cardsIssue a virtual card

GET/wallets/:walletId/cardsList virtual cards

POST/agents/walletsCreate an AI agent wallet

POST/agents/wallets/:agentWalletId/spendExecute an agent spend

GET/agents/wallets/:agentWalletId/historyGet agent spending history

Wallet route overlap

The Financial OS treasury wallet routes (/wallets, /wallets/me, /wallets/:id) share path prefixes with the blockchain Wallets module. The treasury wallet here is ledger-backed and currency-denominated (fiat + stablecoin), distinct from the on-chain blockchain wallet.

Treasury Wallets

POST/walletsCreate a treasury wallet

Request Body

{
"currency": "USD"
}

Field	Type	Required	Description
`currency`	string	No	Settlement currency. Defaults to `USD`.

Creates a user-owned, ledger-backed treasury wallet for the authenticated user.

Ledger History

GET/wallets/:id/ledgerGet double-entry ledger history

Returns the wallet's double-entry ledger entries (debits and credits), most recent first.

Capital — Credit Lines

POST/merchants/:merchantId/capital/credit-linesCreate a credit line

GET/merchants/:merchantId/capital/credit-linesList credit lines

Request Body

{
"amount": 2500000,
"interestRate": 0.12
}

Field	Type	Required	Description
`amount`	number	Yes	Credit line principal in cents
`interestRate`	number	Yes	Annualized interest rate as a decimal (e.g. `0.12` for 12%)

Issuing — Virtual Cards

POST/wallets/:walletId/cardsIssue a virtual card

GET/wallets/:walletId/cardsList virtual cards

Request Body

{
"cardName": "Ads Spend Card",
"spendingLimit": 500000
}

Field	Type	Required	Description
`cardName`	string	Yes	Human-readable card label
`spendingLimit`	number	Yes	Spending limit in cents

Cards are issued against the given treasury wallet and owned by the authenticated user.

AI Agent Wallets

Programmable wallets for autonomous agents with policy-based spending controls.

POST/agents/walletsCreate an AI agent wallet

Request Body

{
"agentId": "agent_abc123",
"dailyLimit": 100000,
"maxTransaction": 25000,
"allowedCategories": ["apis", "inventory"]
}

Field	Type	Required	Description
`agentId`	string	Yes	The agent the wallet belongs to
`dailyLimit`	number	No	Max spend per day in cents
`maxTransaction`	number	No	Max single transaction in cents
`allowedCategories`	string[]	No	Permitted spend categories

Execute a Spend

POST/agents/wallets/:agentWalletId/spendExecute an agent spend

Request Body

{
"amount": 1500,
"currency": "USD",
"rail": "x402",
"description": "Pay inference API per request"
}

Field	Type	Required	Description
`amount`	number	Yes	Spend amount in cents
`currency`	string	Yes	Settlement currency
`rail`	string	Yes	Payment rail (e.g. `card`, `stablecoin`, `x402`)
`description`	string	No	Description recorded with the spend

Policy enforcement

Spends are checked against the wallet's policy (dailyLimit, maxTransaction, allowedCategories) before execution. Spends exceeding limits are rejected.

Spending History

GET/agents/wallets/:agentWalletId/historyGet agent spending history

Returns the agent wallet's spend history, most recent first.