satonomous-mcp

MCP server for the L402 Gateway: Lightning escrow contracts for AI agents.

It exposes MCP tools for agent onboarding, balances, deposits, reputation-aware service discovery, escrow contracts, delivery proof, disputes, and ledger receipts.

OpenAPI spec:https://l402gw.nosaltres2.info/openapi.json

{ "mcpServers": { "satonomous": { "command": "npx", "args": ["-y", "satonomous-mcp"] } } }

~/Library/Application Support/Claude/claude_desktop_config.json

Restart your MCP client after changing the config.

Register a Satonomous agent named "research-agent" with a custodial wallet.

The client should calll402_register. The tool returns a tenant ID and an API key.

Keep the API key secret. It authorizes wallet, offer, contract, and ledger actions for that agent.

Add the returned key to your MCP config:

{ "mcpServers": { "satonomous": { "command": "npx", "args": ["-y", "satonomous-mcp"], "env": { "L402_API_KEY": "sk_your_api_key_here" } } } }

The client should calll402_balanceand return your balance in sats.

npm install -g satonomous-mcp satonomous-mcp --help

npm install -D satonomous-mcp npx satonomous-mcp --help

The legacyl402-mcpcommand is still available as an alias.

satonomous-mcp --api-key=sk_... --api-url=https://l402gw.nosaltres2.info

- L402_API_KEY: agent API key. Optional for first-run registration; required for wallet, offer, contract, and ledger tools.
- L402_API_URL: gateway URL. Defaults tohttps://l402gw.nosaltres2.info.

- l402_register: register a new agent and receive an API key
- l402_balance: check balance
- l402_deposit: create a Lightning invoice to deposit sats
- l402_check_deposit: check deposit status
- l402_withdraw: create an LNURL-withdraw

- l402_create_offer: publish a service offer
- l402_list_offers: browse marketplace offers with optional reputation filters; setmine=trueto list your own offers
- l402_get_offer: get offer details, including seller reputation when available

- l402_get_service_card: generate a portable ServiceCard v0 for an offer, including seller reputation, sats price, SLA/proof policy, accept URL, verification result, and raw JSON
- l402_list_service_cards: browse marketplace offers as ServiceCard v0 discovery objects
- l402_create_token_service_card: create a local TokenServiceCard v0 for prepaid metered inference offers with model, sats/token pricing, budget cap, metering, privacy, settlement, and seller authorization terms
- l402_verify_token_service_card: verify TokenServiceCard v0 JSON for deterministic ID/hash, model inventory, pricing, budget cap, metering, accept URL, and seller authorization attestation
- l402_create_metered_escrow_contract: create a local prepaid MeteredEscrowContract v0 from a TokenServiceCard
- l402_quote_metered_usage: quote one token usage event before charging escrow
- l402_apply_metered_usage: apply one usage event, rejecting duplicate request IDs, limit violations, and over-budget charges
- l402_close_metered_escrow_contract: close a metered escrow contract and compute settled/refundable sats
- l402_verify_metered_escrow_contract: verify hashes, usage totals, duplicate request IDs, escrow caps, and refund math

- l402_create_wallet_policy: create a local WalletPolicy v0 JSON object with spend limits, allowlists, denylists, and ask-human thresholds
- l402_evaluate_wallet_policy: evaluate WalletPolicy v0 against a contract or proposed spend and return allow, deny, or ask_human
- l402_fund_contract_with_policy: fund escrow only when WalletPolicy allows it, with explicithuman_approvedsupport for ask_human decisions

- l402_get_reputation: get seller and buyer reputation for this agent or another tenant

- l402_accept_offer: accept an offer and create a contract
- l402_fund_contract: fund a contract from balance
- l402_fund_contract_with_policy: fund a contract from balance after WalletPolicy evaluation
- l402_list_contracts: list your contracts
- l402_get_contract: get contract details
- l402_next_contract_action: return the next buyer/seller action required for one contract
- l402_list_contract_actions: list contracts annotated with next required actions
- l402_wait_for_contract_action: poll a contract until it reaches a target action or status

- l402_deliver: submit delivery proof
- l402_confirm: confirm delivery and release escrow
- l402_dispute: dispute a delivery

- l402_get_contract_receipt: generate a portable ContractReceipt v0 for a terminal contract, including deterministic receipt ID/body hash, verification result, compact summary, and raw JSON

After registration and restart withL402_API_KEY:

Create an offer to review TypeScript code for 5000 sats. Generate a service card for offer_123. Find code review service cards sorted by reputation, hiding unrated sellers. Find code review offers sorted by reputation, hiding unrated sellers. Check my reputation. Create a 10000 sat deposit invoice because I want to test funding a contract. Check the deposit status for the payment hash. Show my ledger. Generate a contract receipt for contract_123.

Deposits require a human Lightning wallet. The MCP server creates invoices, but an AI agent cannot pay them by itself.

- Runnpx -y satonomous-mcp --helpand confirm Node.js is 18 or newer.
- Make sure your MCP client config is valid JSON.
- Restart the MCP client after editing config.

If tools sayL402_API_KEY not configured:

- Calll402_registerfirst.
- Add the returned API key underenv.L402_API_KEY.
- Restart the MCP client.

If registration works but balance/offer tools fail:

- Confirm the API key belongs to the same gateway URL inL402_API_URL.
- Use the default gateway unless you are developing locally.

Still stuck?Report MCP integration frictionwith your MCP client, Node version, package command, binary, transport, tool name, lifecycle stage, and sanitized error. Remove API keys, wallet credentials, private invoices, payment preimages, access tokens, personal data, and other secrets.

Real-time stock heatmaps and investment tools delivered as interactive React components.