{"openapi":"3.1.0","info":{"title":"Wallet of Agents door","version":"0.21.0","description":"Small custodial Lightning wallets for AI agents. You choose your spend limit, up to 21,000 sats, and we enforce it. Rip-cord: set a return Lightning address, and one call sends your whole balance (less routing fees) to that address only, then freezes the wallet. Custodial; use your own wallet if you can."},"servers":[{"url":"https://walletofagents.dev"}],"paths":{"/woa/health":{"get":{"summary":"Health and version","responses":{"200":{"description":"ok"}}}},"/woa/discover":{"get":{"summary":"Machine-readable discovery","responses":{"200":{"description":"ok"}}}},"/woa/llms.txt":{"get":{"summary":"Plain-text guide for agents","responses":{"200":{"description":"ok"}}}},"/woa/toolkit":{"get":{"summary":"Agent toolkit (markdown)","responses":{"200":{"description":"ok"}}}},"/.well-known/agent-card.json":{"get":{"summary":"Agent card","responses":{"200":{"description":"ok"}}}},"/woa/redeem":{"get":{"summary":"Redeem link info (never burns the token)","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ready"},"400":{"description":"invalid_token"},"404":{"description":"not_found_or_used"},"410":{"description":"already_used or expired"}}},"post":{"summary":"Claim once","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"cap_sats":{"type":"integer","minimum":1,"maximum":21000,"description":"optional spend limit, default 1000"},"return_address":{"type":"string","description":"optional rip-cord return Lightning address, active immediately"}},"required":["token"]}}}},"responses":{"200":{"description":"nwc_url, recovery_secret, cap, return_address"},"400":{"description":"invalid_token, invalid_cap or invalid_return_address (nothing claimed)"},"404":{"description":"not_found_or_used"},"410":{"description":"already_used"}}}},"/woa/cap":{"post":{"summary":"Read or set your spend limit","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"cap_sats":{"type":"integer","minimum":1,"maximum":21000},"low_balance_sats":{"type":"integer","minimum":0,"description":"optional low-balance threshold, default 100; 0 turns the flag off"},"history":{"type":"boolean","description":"include cap_history (append-only cap-change log)"}},"required":["recovery_secret"]}}}},"responses":{"200":{"description":"limit, spent, remaining, balance_sats, max_spendable_now_sats, low_balance, low_balance_threshold_sats, last_topup_at, last_topup_sats, optional cap_history"},"400":{"description":"invalid_cap or invalid_low_balance"},"401":{"description":"auth_failed"},"409":{"description":"wallet_frozen"},"502":{"description":"cap_update_failed"}}}},"/woa/pay":{"post":{"summary":"Pay a BOLT-11 invoice from your wallet, with optional memo and run_id (dry_run:true only checks)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"invoice":{"type":"string","description":"BOLT-11 with an amount"},"memo":{"type":"string","maxLength":140,"description":"optional note, stored and echoed; no secrets or invoices"},"run_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$","description":"optional run id, stored and echoed"},"dry_run":{"type":"boolean","description":"check only: nothing is paid or logged"}},"required":["recovery_secret","invoice"]}}}},"responses":{"200":{"description":"paid (receipt with memo, run_id, payment_hash, fee_sats) or dry_run result (ok, reason, max_spendable_now_sats)"},"400":{"description":"invalid_invoice, invalid_memo or invalid_run_id"},"401":{"description":"auth_failed"},"402":{"description":"spend_refused { reason: amount | fee_reserve | cap | ceiling | balance | frozen, max_spendable_now_sats, needed_sats, cap_remaining_sats, balance_sats }"},"409":{"description":"payment_in_progress, or already_paid { payment_hash, paid_at, receipt } when this wallet already paid the invoice"},"502":{"description":"payment_failed or wallet_read_failed"},"503":{"description":"pay_unavailable or maintenance"}}}},"/woa/ledger":{"post":{"summary":"Read your spend log (door payments with memo and run_id) and cap-change log","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"limit":{"type":"integer","minimum":1,"maximum":500}},"required":["recovery_secret"]}}}},"responses":{"200":{"description":"spends[], cap_history[] (at, old_cap_sats, new_cap_sats, actor, auth, via)"},"401":{"description":"auth_failed"}}}},"/woa/lnaddress":{"post":{"summary":"Read, claim or release your Lightning address handle","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"handle":{"type":["string","null"],"pattern":"^[a-z0-9][a-z0-9._-]{1,30}[a-z0-9]$"},"release":{"type":"boolean"}},"required":["recovery_secret"]}}}},"responses":{"200":{"description":"handle, lightning_address, lnurlp"},"400":{"description":"invalid_handle"},"401":{"description":"auth_failed"},"409":{"description":"handle_unavailable or wallet_frozen"},"429":{"description":"rate_limited"}}}},"/.well-known/lnurlp/{handle}":{"get":{"summary":"LUD-16 payRequest for <handle>@this domain (CORS *)","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tag payRequest, callback, minSendable 1000, maxSendable 21000000, metadata, commentAllowed"},"404":{"description":"Not found (same for unknown, released and frozen)"},"429":{"description":"rate limited"}}}},"/woa/lnurlp/{handle}/callback":{"get":{"summary":"LUD-06 callback: BOLT-11 invoice whose description_hash is sha256(metadata)","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"schema":{"type":"integer","minimum":1000,"maximum":21000000},"description":"msat"},{"name":"comment","in":"query","required":false,"schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"{ pr, routes: [], verify }"},"400":{"description":"amount or comment out of bounds"},"404":{"description":"Not found"},"429":{"description":"rate limited"},"503":{"description":"busy"}}}},"/woa/lnurlp/{handle}/verify/{payment_hash}":{"get":{"summary":"LUD-21 verify","responses":{"200":{"description":"{ status, settled, preimage, pr }"},"404":{"description":"Not found"}}}},"/woa/return-address":{"post":{"summary":"Read, set or clear the rip-cord return address (changes wait 24 h)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"return_address":{"type":["string","null"]}},"required":["recovery_secret"]}}}},"responses":{"200":{"description":"active and pending"},"400":{"description":"invalid_return_address"},"401":{"description":"auth_failed"},"409":{"description":"return_address_locked (24 h after a restore; reads still work)"}}}},"/woa/ripcord":{"post":{"summary":"Send the whole balance to the return address on file, then freeze","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"confirm":{"type":"boolean","const":true},"freeze":{"type":"boolean","default":true}},"required":["recovery_secret","confirm"]}}}},"responses":{"200":{"description":"sent or no-op"},"400":{"description":"confirm_required or destination_not_allowed"},"401":{"description":"auth_failed"},"409":{"description":"no_return_address or ripcord_in_progress"},"502":{"description":"ripcord_failed"},"503":{"description":"unavailable or maintenance"}}}},"/woa/restore":{"post":{"summary":"Re-issue a lost wallet connection","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_secret":{"type":"string","description":"woa_rec_ followed by 64 hex, from your claim"},"dryRun":{"type":"boolean"}},"required":["recovery_secret"]}}}},"responses":{"200":{"description":"nwc_url and a new recovery_secret"},"401":{"description":"restore_failed"},"409":{"description":"restore_locked (24 h after a return-address change, or while one is pending)"}}}}}}