{"openapi":"3.0.0","info":{"title":"Minibits Ippon API","description":"Minimalistic, API-driven ecash and Lightning wallet implementing the Cashu protocol. Designed for AI agents and automated systems requiring instant micropayment capability.","version":"1.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Wallet access key returned at wallet creation. Pass as: Authorization: Bearer <access_key>"}},"schemas":{}},"paths":{"/v1/info":{"get":{"tags":["Info"],"description":"Returns machine-readable information about the wallet service: status, supported mints, unit, and global balance/payment limits (including rate limits).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"operational"},"help":{"type":"string"},"terms":{"type":"string"},"unit":{"type":"string","enum":["sat","msat"]},"mints":{"type":"array","items":{"type":"string"},"description":"List of supported Cashu mint URLs"},"limits":{"type":"object","properties":{"max_balance":{"type":"integer"},"max_send":{"type":"integer"},"max_pay":{"type":"integer"},"rate_limit_max":{"type":"integer","description":"Max requests per time window (global)"},"rate_limit_create_wallet_max":{"type":"integer","description":"Max wallet creations per time window per IP"},"rate_limit_window":{"type":"string","description":"Rate-limit time window (e.g. \"1 minute\")"}}}}}}}}}}},"/v1/wallet":{"post":{"tags":["Wallet"],"description":"Create a new short-lived wallet. Optionally specify a supported mint URL (defaults to the first configured mint), provide a name, wallet-level limits, and an initial Cashu token to fund it immediately.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional label for the wallet"},"token":{"type":"string","description":"Optional Cashu token (cashuB...) to deposit on creation"},"mint_url":{"type":"string","description":"Mint URL to bind this wallet to. Must be one of the supported mints. Defaults to the first configured mint."},"limits":{"type":"object","description":"Optional per-wallet spending caps. Values are capped to the global operator limits.","properties":{"max_balance":{"type":"integer","description":"Max wallet balance (in unit). Capped to global MAX_BALANCE."},"max_send":{"type":"integer","description":"Max ecash send amount. Capped to global MAX_SEND."},"max_pay":{"type":"integer","description":"Max Lightning payment amount. Capped to global MAX_PAY."}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"access_key":{"type":"string","description":"Bearer token for all subsequent authenticated requests"},"mint":{"type":"string"},"unit":{"type":"string"},"balance":{"type":"integer"},"pending_balance":{"type":"integer"},"limits":{"type":"object","nullable":true,"properties":{"max_balance":{"type":"integer","nullable":true},"max_send":{"type":"integer","nullable":true},"max_pay":{"type":"integer","nullable":true}}}}}}}}}},"get":{"tags":["Wallet"],"description":"Get the current wallet details including name, unit, mint, confirmed balance, and pending balance. Any pending proofs are checked against the mint first and their state updated before the balances are calculated.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"access_key":{"type":"string"},"mint":{"type":"string"},"unit":{"type":"string"},"balance":{"type":"integer"},"pending_balance":{"type":"integer"},"limits":{"type":"object","nullable":true,"properties":{"max_balance":{"type":"integer","nullable":true},"max_send":{"type":"integer","nullable":true},"max_pay":{"type":"integer","nullable":true}}}}}}}}}}},"/v1/wallet/deposit":{"post":{"tags":["Deposit"],"description":"Request a Lightning invoice to fund the wallet. The wallet automatically handles the mint quote and ecash issuance once the invoice is paid.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","unit"],"properties":{"amount":{"type":"integer","description":"Amount to deposit (in wallet unit)"},"unit":{"type":"string","enum":["sat","msat"]}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"string"},"request":{"type":"string","description":"BOLT11 Lightning invoice"},"state":{"type":"string","enum":["UNPAID","PAID","ISSUED","EXPIRED"]},"expiry":{"type":"integer"}}}}}}}}},"/v1/wallet/deposit/{quote}":{"get":{"tags":["Deposit"],"description":"Check deposit status. Automatically mints ecash when the invoice is paid.","parameters":[{"schema":{"type":"string"},"in":"path","name":"quote","required":true,"description":"Quote ID returned by POST /wallet/deposit"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"string"},"request":{"type":"string","description":"BOLT11 Lightning invoice"},"state":{"type":"string","enum":["UNPAID","PAID","ISSUED","EXPIRED"]},"expiry":{"type":"integer"}}}}}}}}},"/v1/wallet/send":{"post":{"tags":["Send"],"description":"Export an ecash token for a specified amount. The wallet handles all necessary proof swaps and marks sent proofs as pending to prevent double-spending. Mint fees are paid by the sender. Optionally lock the token to a recipient pubkey (NUT-11 P2PK).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","unit"],"properties":{"amount":{"type":"integer"},"unit":{"type":"string","enum":["sat","msat"]},"memo":{"type":"string","description":"Optional memo embedded in the token"},"lock_to_pubkey":{"type":"string","description":"Lock token to a pubkey (NUT-11 P2PK). Accepts npub, 64-char x-only hex, or 66-char compressed hex."},"cashu_request":{"type":"string","description":"Pay a Cashu payment request (not yet implemented)"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Encoded Cashu token (cashuB...)"},"amount":{"type":"integer"},"unit":{"type":"string"},"memo":{"type":"string","nullable":true}}}}}}}}},"/v1/wallet/check":{"post":{"tags":["Send"],"description":"Check the current state of an exported Cashu token (e.g., whether it has been spent or swapped by the recipient).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Cashu token to check"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"},"unit":{"type":"string"},"memo":{"type":"string","nullable":true},"state":{"type":"string","enum":["UNSPENT","SPENT","PENDING","MIXED","UNKNOWN"]},"mint_proof_states":{"type":"array","items":{"type":"object","properties":{"Y":{"type":"string","description":"Hash-to-curve of the proof secret"},"state":{"type":"string","enum":["UNSPENT","PENDING","SPENT"]},"witness":{"type":"string","nullable":true}},"additionalProperties":true}}}}}}}}}},"/v1/wallet/decode":{"post":{"tags":["Utils"],"description":"Decode a Cashu token, Cashu payment request, or BOLT11 invoice and return structured information.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","enum":["CASHU_TOKEN_V4","CASHU_TOKEN_V3","BOLT11_REQUEST","CASHU_REQUEST"]},"data":{"type":"string"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"decoded":{"type":"object","additionalProperties":true}}}}}}}}},"/v1/wallet/pay":{"post":{"tags":["Pay"],"description":"Pay a BOLT11 Lightning invoice or Lightning address using the wallet's ecash balance. The wallet handles the melt quote, fees, and returns any change.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","unit"],"properties":{"bolt11_request":{"type":"string","description":"BOLT11 invoice to pay"},"lightning_address":{"type":"string","description":"Lightning address (e.g. user@domain.com)"},"amount":{"type":"integer"},"unit":{"type":"string","enum":["sat","msat"]}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"string"},"amount":{"type":"integer"},"fee_reserve":{"type":"integer"},"state":{"type":"string","enum":["UNPAID","PENDING","PAID"]},"payment_preimage":{"type":"string","nullable":true},"expiry":{"type":"integer"}}}}}}}}},"/v1/wallet/pay/{quote}":{"get":{"tags":["Pay"],"description":"Check the status of a melt quote / payment operation (e.g., whether the invoice was successfully paid).","parameters":[{"schema":{"type":"string"},"in":"path","name":"quote","required":true,"description":"Quote ID returned by POST /wallet/pay"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"string"},"amount":{"type":"integer"},"fee_reserve":{"type":"integer"},"state":{"type":"string","enum":["UNPAID","PENDING","PAID"]},"payment_preimage":{"type":"string","nullable":true},"expiry":{"type":"integer"}}}}}}}}},"/v1/wallet/receive":{"post":{"tags":["Receive"],"description":"Import an external Cashu token. The wallet validates the token with the mint and swaps it for a fresh ecash token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Cashu token to receive (cashuB...)"}}}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"},"unit":{"type":"string"},"balance":{"type":"integer"},"pending_balance":{"type":"integer"}}}}}}}}},"/v1/rate/{currency}":{"get":{"tags":["Utils"],"description":"Get the current fiat exchange rate for the wallet's unit (e.g., satoshis per USD).","parameters":[{"schema":{"type":"string"},"in":"path","name":"currency","required":true,"description":"ISO 4217 currency code (e.g. USD, EUR)"}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"rate":{"type":"number","description":"Satoshis per 1 unit of currency"},"timestamp":{"type":"integer","description":"Unix timestamp of the rate"}}}}}}}}}}}