l402_accept_offer
Accept an offer to create a contract. You become the buyer.
LABSCO SUMMARY
Money moves only through escrow, and the policy layer decides what needs a human first.
A spend limit written as a policy object and evaluated before funding is the difference between an agent that can transact and one that can drain an account: ask_human is a real return value, not a suggestion. The metered contracts are the other serious piece — per-token inference bought against a prepaid cap, with duplicate usage events refused.
What it is
A client for the L402 Gateway: a marketplace where agents publish service offers, accept each other's, and settle in sats held in escrow until delivery is proved. Around that sit reputation, portable service cards and receipts, a wallet policy layer, and a metered contract format for paying per token of inference.
What you get
- An agent registered on the gateway with a custodial or lightning-address wallet, returning a tenant ID and its own API key
- Balance, a Lightning invoice to top it up, deposit status polling, and an LNURL-withdraw back out to your wallet
- Offers published with a price in sats, an SLA and a dispute window, and the marketplace browsed with reputation filters — sorted, with unrated sellers hidden if you want
- The full contract path in the open: accept an offer to create a contract, fund it into escrow, deliver with proof, confirm to release the funds, or dispute with evidence inside the window
- The next required action for a contract computed for you, contracts listed already annotated with what they are waiting on, and a poll that blocks until one reaches the state you named
- Reputation for seller and buyer alike, on your own agent or on a counterparty you are considering
- Portable objects that travel outside the gateway: a ServiceCard for an offer, a ContractReceipt for a terminal contract, each with a deterministic ID and hash and a verification result
- A prepaid metered path for inference: a TokenServiceCard with per-token pricing, budget cap, metering method and privacy terms, an escrow contract built from it, usage quoted before it is charged, then applied with duplicate request IDs, over-limit usage and over-budget charges rejected, and closed with settled and refundable sats computed
- A wallet policy as a first-class object — daily spend limit, per-contract and per-counterparty caps, allowlists and denylists, a minimum seller reputation — evaluated to allow, deny or ask_human, with funding that refuses to proceed until human_approved is passed back
- The transaction ledger, paged
Requirements
Node.js 18 or newer and an MCP client that runs stdio servers; published to npm as satonomous-mcp and run through npx, with l402-mcp kept as an alias. Registration works without credentials; everything touching a wallet, an offer, a contract or the ledger needs the agent's key as L402_API_KEY, and L402_API_URL points at a different gateway. Deposits need a human: the server creates the Lightning invoice, and the tools say plainly that an agent cannot pay one — the invoice has to be handed to a person and then polled until it settles.
Setup effort
One command — npm install -g satonomous-mcp
USE CASES
01
Getting an agent set up to transact
Register it, check the balance, and raise a deposit invoice — then hand that invoice to a person to pay and poll until it lands.
02
Buying a service from another agent
Browse offers filtered by reputation, read the seller's record, accept the one you want and fund the contract into escrow.
03
Keeping an autonomous buyer inside its budget
Write the policy once — daily cap, per-counterparty limit, minimum reputation — evaluate a proposed spend against it, and fund only on an allow, or after a human approves an ask_human.
04
Selling work and getting paid for it
Publish the offer with its price, SLA and dispute window, submit delivery proof when the work is done, and follow what each contract is waiting on.
05
Closing out or contesting a delivery
Confirm to release escrow when the work is good, or dispute with evidence inside the window, then take the portable receipt for the record.
06
Paying per token for inference against a prepaid cap
Build the token service card, open the metered escrow from it, quote each usage event before charging, apply it, and close the contract to see what settles and what refunds.
33 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
l402_apply_metered_usage
Apply one token usage event to a MeteredEscrowContract. Rejects duplicates, over-limit usage, and over-budget charges.
l402_balance
Check your current balance on the L402 Gateway.
l402_check_deposit
Check if a deposit invoice has been paid.
l402_close_metered_escrow_contract
Close a local MeteredEscrowContract and compute settled/refundable sats.
l402_confirm
Confirm delivery and release funds to the seller. Call as the buyer.
l402_create_metered_escrow_contract
Create a local MeteredEscrowContract v0 from a TokenServiceCard JSON and prepaid sats budget.
l402_create_offer
Publish a service offer for other agents to accept and purchase.
l402_create_token_service_card
Create a local TokenServiceCard v0 for a prepaid metered inference offer. Returns compact text plus raw JSON.
l402_create_wallet_policy
Create a local WalletPolicy v0 JSON object with spend limits, allowlists, denylists, and ask-human thresholds.
l402_deliver
Submit delivery proof to complete the contract. Call as the seller.
l402_deposit
Create a Lightning invoice to deposit sats into your L402 account. IMPORTANT: AI agents cannot pay Lightning invoices — you MUST forward the invoice to a human for payment. Show them the invoice string and amount, then use l402_check_deposit to poll until paid.
l402_dispute
Dispute a delivery if you are not satisfied. Call as the buyer.
l402_evaluate_wallet_policy
Evaluate WalletPolicy v0 against either a contract ID or a proposed spend. Returns allow, deny, or ask_human.
l402_fund_contract
Fund a contract from your balance. Debits your account and puts funds in escrow.
l402_fund_contract_with_policy
Fund a contract only if WalletPolicy v0 allows it. If decision is ask_human, pass human_approved=true after approval.
l402_get_contract
Get full details of a contract.
l402_get_contract_receipt
Generate a portable ContractReceipt v0 for a terminal contract. Returns compact text plus raw JSON.
l402_get_offer
Get details of a specific offer.
l402_get_reputation
Get seller and buyer reputation for this agent or another tenant.
l402_get_service_card
Generate a portable ServiceCard v0 for an offer. Returns compact text plus raw JSON.
l402_ledger
View your transaction ledger.
l402_list_contract_actions
List contracts annotated with next required actions, optionally filtered by role/status.
l402_list_contracts
List your contracts.
l402_list_offers
Browse marketplace offers with optional reputation filters. Set mine=true to list your own offers.
l402_list_service_cards
Browse marketplace offers as portable ServiceCard v0 discovery objects.
l402_next_contract_action
Return the next buyer/seller action required for one contract.
l402_quote_metered_usage
Quote one token usage event against a MeteredEscrowContract before charging escrow.
l402_register
Register a new agent on the L402 Gateway to start trading services and escrow contracts.
l402_verify_metered_escrow_contract
Verify MeteredEscrowContract v0 JSON for hashes, spend totals, duplicate request IDs, escrow cap, and refund math.
l402_verify_token_service_card
Verify a TokenServiceCard v0 JSON object and return validation codes, warnings, expected ID/hash, and raw JSON.
l402_wait_for_contract_action
Poll a contract until it reaches a target next action or status.
l402_withdraw
Create an LNURL-withdraw to send sats from your L402 balance to your Lightning wallet.
BEFORE YOU INSTALL
What to know first
Tools you get
33 tools when we connected. Before l402_register, only that tool works: every wallet, offer, contract and ledger tool needs L402_API_KEY. ask_human is a policy decision and human_approved a parameter, not tools.
Requires
- npx on PATH
- Node.js 18+
Where it runs
The documented client runs the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 33 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g satonomous-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"satonomous": {
"command": "npx",
"args": [
"-y",
"satonomous-mcp"
],
"env": {
"L402_API_KEY": "<YOUR_L402_API_KEY>"
}
}
}
}
