{"service":{"name":"FreedomPayments","tagline":"Sell anything. Get paid in crypto.","summary":"Non-custodial crypto payment gateway for merchants. A merchant creates payment units (one offer: title, USD price, currencies, wait time), embeds or shares a checkout surface, and buyers pay on-chain straight into the merchant's own wallets. The platform watches the chain, confirms the payment, posts a webhook and debits a prepaid service balance for the fee.","network":"mainnet","demo_mode":false,"fiat":"USD","platform_fee_rate":"0.01","service_fee_percent":"0","max_payment_units":3,"base_url":"https://api.freedompayments.tech","frontend_host":"https://freedompayments.tech"},"auth":{"none":{"id":"none","type":"none","summary":"Public — no credentials required."},"merchant_key":{"id":"merchant_key","type":"apiKey","in":"header","name":"X-API-Key","summary":"Merchant key (fp_…) from GET /api/v1/merchant/account, sent as the X-API-Key header (or ?api_key= query). The platform key creates legacy invoices against env-configured wallets."},"jwt":{"id":"jwt","type":"http","scheme":"bearer","summary":"Merchant session token from POST /api/v1/login/access-token, sent as Authorization: Bearer <token>."},"admin_jwt":{"id":"admin_jwt","type":"http","scheme":"bearer","summary":"Superuser session token — platform operators only."}},"kinds":["flow","endpoint","page","embed","concept","guide"],"counts":{"flow":7,"endpoint":69,"page":6,"embed":3,"concept":7,"guide":6},"capabilities":[{"id":"flow.accept_payment","kind":"flow","title":"Take one payment for a unit (buyer path)","summary":"Read the unit → POST /v1/units/{id}/checkout with a chain → show /v1/pay/{invoice_id}/page (or the QR payload) to the buyer → poll the invoice until status is confirmed/expired.","auth":"none","when_to_use":"An agent or shop integration must collect a payment for a known offer. No credentials are needed for the public path.","example":"# 1. what can this unit accept?\ncurl -s https://api.freedompayments.tech/v1/units/{unit_id}\n# 2. create the invoice\ncurl -s -X POST https://api.freedompayments.tech/v1/units/{unit_id}/checkout \\\n  -H \"Content-Type: application/json\" -d '{\"chain\":\"ton\"}'\n# 3. buyer pays: open page_url, or scan qr_payload\n# 4. poll until terminal\ncurl -s https://api.freedompayments.tech/v1/public/invoices/{invoice_id}","returns":"InvoicePublic: address, memo, amount, expires_at, status, page_url/div_url/qr_url/qr_png_url/qr_payload.","keywords":["payment","checkout","buy","pay","purchase","collect payment","invoice","buyer"],"related":["endpoint.unit.checkout","flow.watch_invoice","endpoint.pay.page","endpoint.invoice.public_get","flow.accept_payment_telegram"],"source":"docs/how-it-works.md","source_anchor":"the-six-steps"},{"id":"flow.accept_payment_telegram","kind":"flow","title":"Accept crypto payments in a Telegram bot","summary":"Create the invoice with the merchant key, send the requisites plus the QR PNG as a photo (sendPhoto rejects SVG), then confirm via both webhook branches or by polling, and deliver the goods exactly once with one conditional UPDATE.","auth":"merchant_key","when_to_use":"A bot, mini-app or chat integration must charge in crypto: this is the end-to-end path with the chat-specific traps already handled.","example":"# 1. invoice (external_ref = your order id)\ncurl -s -X POST https://api.freedompayments.tech/v1/invoices \\\n  -H \"X-API-Key: $FP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"chain\":\"ton\",\"amount\":\"3.30\",\"amount_unit\":\"usd\",\"external_ref\":\"order-42\"}'\n# 2. QR as PNG: Telegram cannot send SVG\ncurl -s https://api.freedompayments.tech/v1/pay/{invoice_id}/qr.png -o qr.png\n# 3. poll the truth (or accept the webhook as a fast path)\ncurl -s https://api.freedompayments.tech/v1/public/invoices/{invoice_id}","returns":"A paid order: status confirmed/settled, then one idempotent delivery (UPDATE … WHERE status IN ('created','failed') + claim).","keywords":["telegram","bot","sendphoto","qr png","qr_png_url","chat","miniapp","mini app","aiohttp","tutorial","quickstart","beginner"],"related":["endpoint.invoice.create","endpoint.pay.qr_png","flow.watch_invoice","guide.quickstart_telegram_bot","endpoint.invoice.public_get"],"source":"docs/quickstart-telegram-bot.md","source_anchor":"the-shape-of-it"},{"id":"flow.embed_checkout","kind":"flow","title":"Put checkout on a website or app","summary":"Pick a surface: Mobile embed, Desktop embed, or Site page. Either drop the embed.js script tag (auto-mounts the div) or iframe the div/page URL directly.","auth":"none","when_to_use":"A task says 'add a crypto buy button', 'embed checkout', 'put this on my landing page'.","example":"<div id=\"fp-unit-coffee-mobile\"></div>\n<script src=\"https://api.freedompayments.tech/embed.js\" data-unit=\"{unit_id}\"\n        data-size=\"mobile\" data-target=\"#fp-unit-coffee-mobile\" async></script>","returns":"A mounted checkout that creates invoices on demand.","keywords":["embed","iframe","widget","script tag","embed.js","buy button","landing page","integration"],"related":["concept.surfaces","endpoint.unit.div","endpoint.unit.page"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"flow.refill_prepaid","kind":"flow","title":"Top up the prepaid balance","summary":"GET /api/v1/merchant/refill-wallets lists platform addresses; POST /api/v1/merchant/refill creates a refill invoice. Paying sum S credits S × 100 to limit_of_payments. TON/Solana wait 5 minutes, Bitcoin 1 hour.","auth":"jwt","when_to_use":"Before a merchant can be observed for payments, for example after HTTP 402 from /check or when /balances shows no remaining limit.","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/refill-wallets -H \"Authorization: Bearer $TOKEN\"\ncurl -s -X POST https://api.freedompayments.tech/api/v1/merchant/refill -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" -d '{\"chain\":\"ton\",\"amount_usd\":\"10\"}'","returns":"A refill InvoicePublic to pay, then a growing limit_of_payments.","keywords":["refill","top up","topup","deposit","fund","credit","prepaid","insufficient limit"],"related":["concept.prepaid_limit","endpoint.merchant.balances"],"source":"docs/workflow.md","source_anchor":"a1--refill-prepaid"},{"id":"flow.sell_unit","kind":"flow","title":"Onboard a merchant: from zero to a sellable unit","summary":"Create an account → top up prepaid → set a receive wallet → create a payment unit → share or embed it. This is track A of the workflow.","auth":"jwt","when_to_use":"A human or agent says 'I want to sell something with this service' and has no account yet.","example":"# 1. account\ncurl -s -X POST https://api.freedompayments.tech/api/v1/users/signup -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"me@example.com\",\"password\":\"changeme123\"}'\n# 2. token\nTOKEN=$(curl -s -X POST https://api.freedompayments.tech/api/v1/login/access-token \\\n  -d \"username=me@example.com&password=changeme123\" | jq -r .access_token)\n# 3. receive wallet for TON\ncurl -s -X PUT https://api.freedompayments.tech/api/v1/merchant/wallets -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" -d '{\"chain\":\"ton\",\"address\":\"EQ...\"}'\n# 4. refill prepaid (returns an invoice to pay)\ncurl -s -X POST https://api.freedompayments.tech/api/v1/merchant/refill -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" -d '{\"chain\":\"ton\",\"amount_usd\":\"1\"}'\n# 5. create the unit\ncurl -s -X POST https://api.freedompayments.tech/api/v1/merchant/units -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"Coffee\",\"amount_usd\":4.5,\"currencies\":[\"ton\"],\"wait_seconds\":1800}'","returns":"A unit object with page_url, embed_small_url, embed_big_url and surfaces[].","keywords":["onboard","get started","sell","start selling","merchant setup","sign up","end to end","tutorial"],"related":["endpoint.users.signup","endpoint.login.access_token","endpoint.merchant.wallets.put","flow.refill_prepaid","endpoint.merchant.units.create","flow.embed_checkout"],"source":"docs/workflow.md","source_anchor":"track-a--merchant-readiness-detailed"},{"id":"flow.test_payment_without_crypto","kind":"flow","title":"Test the whole flow without spending crypto","summary":"On testnet with DEMO_MODE=true, create an invoice then POST /v1/invoices/{id}/simulate to mark it paid, which exercises settlement, the fee debit and the merchant webhook.","auth":"merchant_key","when_to_use":"Verifying an integration, writing tests, or demonstrating the product end-to-end without funds.","example":"curl -s -X POST https://api.freedompayments.tech/v1/invoices/{invoice_id}/simulate \\\n  -H \"X-API-Key: $FP_KEY\"","returns":"The invoice in its post-settlement state.","keywords":["simulate","demo","test","fake payment","sandbox","testnet","no funds"],"related":["endpoint.invoice.simulate","endpoint.config.public"],"source":"docs/workflow.md","source_anchor":"end-to-end-story-happy-path"},{"id":"flow.watch_invoice","kind":"flow","title":"Watch an invoice until it is paid or expires","summary":"Poll GET /v1/public/invoices/{id} (no auth) for status, or POST /v1/invoices/{id}/check to force one chain poll. Terminal states: confirmed, expired, cancelled, failed. On confirm the merchant webhook fires and the prepaid fee is debited.","auth":"none","when_to_use":"Any agent waiting for money. Prefer webhooks for production and polling for interactive flows.","example":"until curl -s https://api.freedompayments.tech/v1/public/invoices/{invoice_id} | grep -q confirmed; do\n  sleep 10\ndone","returns":"status plus txid, confirmations, received_amount, amount_match, paid_at.","keywords":["poll","wait","status","confirm","webhook","until paid","watch","monitor"],"related":["endpoint.invoice.public_get","endpoint.invoice.check","endpoint.invoice.payment"],"source":"docs/workflow.md","source_anchor":"b3--observation"},{"id":"endpoint.agent-get_catalog","kind":"endpoint","title":"Get Catalog","summary":"Full capability catalog — flows, endpoints, pages, embeds, concepts, guides.","auth":"none","method":"GET","path":"/v1/catalog","url":"https://api.freedompayments.tech/v1/catalog","params":[{"name":"kind","in":"query","required":false,"type":"enum(flow|endpoint|page|embed|concept|guide)","description":"Only return capabilities of this kind.","enum":["flow","endpoint","page","embed","concept","guide"]},{"name":"format","in":"query","required":false,"type":"enum(json|markdown)","description":"json (default) or markdown for prompt-friendly text.","enum":["json","markdown"]},{"name":"include_docs","in":"query","required":false,"type":"boolean","description":"Include the full text of the documentation sections."},{"name":"brief","in":"query","required":false,"type":"boolean","description":"Index-only view (id, kind, title, summary, url, auth) — a small payload for planning before fetching details."},{"name":"include_hidden","in":"query","required":false,"type":"boolean","description":"Include operator-only capabilities (superuser API). Off by default: those surfaces are deliberately undocumented."}],"keywords":["agent"],"auto":true},{"id":"endpoint.agent-search_capabilities","kind":"endpoint","title":"Search Capabilities","summary":"Search this service by intent; every hit carries a ready-to-run call.","auth":"none","method":"GET","path":"/v1/search","url":"https://api.freedompayments.tech/v1/search","params":[{"name":"q","in":"query","required":false,"type":"string","description":"Natural-language intent, e.g. 'create an invoice', 'refill limit', 'embed a buy button'."},{"name":"limit","in":"query","required":false,"type":"integer"},{"name":"kind","in":"query","required":false,"type":"enum(flow|endpoint|page|embed|concept|guide)","description":"Restrict results to one kind.","enum":["flow","endpoint","page","embed","concept","guide"]},{"name":"include_docs","in":"query","required":false,"type":"boolean","description":"Search documentation sections too (default true)."},{"name":"include_hidden","in":"query","required":false,"type":"boolean","description":"Also match operator-only capabilities (off by default)."}],"keywords":["agent"],"auto":true},{"id":"endpoint.agent_manifest","kind":"endpoint","title":"Agent manifest (/.well-known/agent.json)","summary":"Machine-readable service manifest: identity, auth schemes, transports and links to catalog, search, llms.txt and OpenAPI.","auth":"none","when_to_use":"Automated discovery from a domain name alone.","method":"GET","path":"/.well-known/agent.json","url":"https://api.freedompayments.tech/.well-known/agent.json","example":"curl -s https://api.freedompayments.tech/.well-known/agent.json","returns":"JSON manifest.","keywords":["well-known","manifest","discovery","agent.json","metadata"],"related":["endpoint.catalog","endpoint.openapi"],"source":"docs/agent-access.md"},{"id":"endpoint.catalog","kind":"endpoint","title":"Full capability catalog (machine-readable)","summary":"Every capability in this service as JSON: flows, endpoints, pages, embeds, concepts and guides, each with url, auth, params, example and related ids. Filter with ?kind= or render as markdown with ?format=markdown.","auth":"none","when_to_use":"Fetch once to plan a whole task offline, or after a search hit to expand neighbouring capabilities.","method":"GET","path":"/v1/catalog","url":"https://api.freedompayments.tech/v1/catalog","example":"curl -s https://api.freedompayments.tech/v1/catalog","returns":"JSON catalog (or markdown with ?format=markdown).","keywords":["catalog","capabilities","index","everything","api list","what can you do"],"related":["endpoint.search","concept.overview"],"source":"docs/agent-access.md"},{"id":"endpoint.config.public","kind":"endpoint","title":"Public runtime configuration","summary":"Network, demo_mode, service fee, platform fee rate, fiat defaults, memo length, public base URL, max units, enabled social logins.","auth":"none","when_to_use":"To learn whether simulate is allowed, what the fee is, or which auth providers this deployment offers.","method":"GET","path":"/v1/config/public","url":"https://api.freedompayments.tech/v1/config/public","example":"curl -s https://api.freedompayments.tech/v1/config/public","returns":"Flat JSON config object.","keywords":["config","settings","fee","network","demo","testnet","limits"],"related":["concept.fees","flow.test_payment_without_crypto"],"source":"docs/merchant.md","source_anchor":"config-reference"},{"id":"endpoint.embed_script","kind":"endpoint","title":"Embed Script","summary":"Embed Script","auth":"none","method":"GET","path":"/embed.js","url":"https://api.freedompayments.tech/embed.js","auto":true},{"id":"endpoint.exits.tg","kind":"endpoint","title":"Telegram payment deeplink","summary":"Telegram wallet deeplink for the invoice.","auth":"none","when_to_use":"Buyer prefers paying from a Telegram wallet.","method":"GET","path":"/v1/exits/{invoice_id}/tg","url":"https://api.freedompayments.tech/v1/exits/{invoice_id}/tg","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/exits/{invoice_id}/tg","returns":"Deeplink payload object.","keywords":["telegram","deeplink","wallet","exit"],"related":["endpoint.exits.web"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.exits.web","kind":"endpoint","title":"Alternative web payment payload","summary":"Payload for paying the invoice through a web wallet flow instead of a raw address+memo transfer.","auth":"none","when_to_use":"When the buyer's wallet cannot do a memo transfer.","method":"GET","path":"/v1/exits/{invoice_id}/web","url":"https://api.freedompayments.tech/v1/exits/{invoice_id}/web","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/exits/{invoice_id}/web","returns":"Exit payload object.","keywords":["exit","web wallet","alternative payment","deeplink"],"related":["endpoint.exits.tg"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.favicon","kind":"endpoint","title":"Favicon","summary":"Favicon","auth":"none","method":"GET","path":"/favicon-32.png","url":"https://api.freedompayments.tech/favicon-32.png","auto":true},{"id":"endpoint.gateways.list","kind":"endpoint","title":"List supported chains and currencies","summary":"Every chain/currency the deployment accepts, with decimals, confirmations, memo support, TTL, poll interval and exit links, grouped by blockchain.","auth":"none","when_to_use":"Always the first call when you need to know what a buyer can pay with, or which chain id to pass to checkout.","method":"GET","path":"/v1/gateways","url":"https://api.freedompayments.tech/v1/gateways","params":[{"name":"network","in":"response","required":false,"type":"str"}],"example":"curl -s https://api.freedompayments.tech/v1/gateways","returns":"GatewaysResponse: data[], groups[], network, fee defaults.","keywords":["chains","currencies","supported","gateways","btc","ton","solana","usdt","usdc","coins"],"related":["concept.overview","endpoint.invoice.create"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.health","kind":"endpoint","title":"Payments health check","summary":"Liveness probe for the payments engine.","auth":"none","when_to_use":"Monitoring or before starting a long agent workflow.","method":"GET","path":"/health","url":"https://api.freedompayments.tech/health","example":"curl -s https://api.freedompayments.tech/health","returns":"{\"message\":\"ok\"}","keywords":["health","status","alive","probe","uptime"],"source":"README.md"},{"id":"endpoint.invoice.cancel","kind":"endpoint","title":"Cancel an invoice (buyer)","summary":"Stops observation of a pending payment. Public — the buyer decides.","auth":"none","when_to_use":"The buyer abandons checkout and you want to close the invoice.","method":"POST","path":"/v1/invoices/{invoice_id}/cancel","url":"https://api.freedompayments.tech/v1/invoices/{invoice_id}/cancel","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/v1/invoices/{invoice_id}/cancel","returns":"InvoicePublic with status cancelled.","keywords":["cancel","abort","stop watching","expire now"],"related":["flow.watch_invoice"],"source":"docs/workflow.md","source_anchor":"b2--present-pay-ui--cancel"},{"id":"endpoint.invoice.check","kind":"endpoint","title":"Force one chain poll for an invoice","summary":"Asks the gateway to look at the chain right now instead of waiting for the observer cadence. Returns HTTP 402 when the merchant's prepaid limit is below the invoice volume.","auth":"merchant_key","when_to_use":"A buyer just paid and you want confirmation without waiting for the next poll tick.","method":"POST","path":"/v1/invoices/{invoice_id}/check","url":"https://api.freedompayments.tech/v1/invoices/{invoice_id}/check","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"},{"name":"api_key","in":"query","required":false,"type":"string"},{"name":"x-api-key","in":"header","required":false,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/v1/invoices/{invoice_id}/check -H \"X-API-Key: $FP_KEY\"","returns":"Updated InvoicePublic; 402 details when the prepaid gate blocks it.","keywords":["check payment","verify payment","poll now","did it arrive","confirm","402"],"related":["flow.watch_invoice","concept.prepaid_limit"],"source":"docs/workflow.md","source_anchor":"b3--observation"},{"id":"endpoint.invoice.create","kind":"endpoint","title":"Create a payment invoice","summary":"Create an invoice for a fiat (USD) or native amount on one chain. With a merchant key it uses that merchant's wallet, prepaid limit and webhook; with the platform key it uses env-configured wallets.","auth":"merchant_key","when_to_use":"Selling an arbitrary amount that is not one of the merchant's payment units (for units prefer endpoint.unit.checkout).","method":"POST","path":"/v1/invoices","url":"https://api.freedompayments.tech/v1/invoices","params":[{"name":"chain","in":"body","required":true,"type":"str"},{"name":"amount","in":"body","required":true,"type":"decimal","description":"USD by default, native when amount_unit=native."},{"name":"amount_unit","in":"body","required":false,"type":"enum(usd|native)"},{"name":"external_ref","in":"body","required":false,"type":"str"},{"name":"callback_url","in":"body","required":false,"type":"url"}],"example":"curl -s -X POST https://api.freedompayments.tech/v1/invoices \\\n  -H \"X-API-Key: $FP_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"chain\":\"ton\",\"amount\":\"4.50\",\"amount_unit\":\"usd\",\"external_ref\":\"order-42\",\"callback_url\":\"https://shop.example/webhook\"}'","returns":"InvoicePublic including address, memo, expires_at and pay/qr URLs.","keywords":["create invoice","new invoice","charge","request payment","sell","amount","order"],"related":["endpoint.unit.checkout","flow.watch_invoice","concept.invoice_vs_payment"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.invoice.get","kind":"endpoint","title":"Read an invoice (merchant key)","summary":"Invoice state for the key owner; other owners get 404.","auth":"merchant_key","when_to_use":"Server-side order reconciliation for your own merchant account.","method":"GET","path":"/v1/invoices/{invoice_id}","url":"https://api.freedompayments.tech/v1/invoices/{invoice_id}","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"},{"name":"api_key","in":"query","required":false,"type":"string"},{"name":"x-api-key","in":"header","required":false,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/invoices/{invoice_id} -H \"X-API-Key: $FP_KEY\"","returns":"InvoicePublic.","keywords":["invoice status","read invoice","order status","check payment"],"related":["endpoint.invoice.public_get","endpoint.invoice.payment"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.invoice.payment","kind":"endpoint","title":"Read the on-chain payment and its status log","summary":"Payment record for an invoice: status, txid, confirmations, received_amount, amount_match and the full status transition log.","auth":"none","when_to_use":"Debugging 'why is this not confirmed yet', or when you need the txid or the amount mismatch reason.","method":"GET","path":"/v1/invoices/{invoice_id}/payment","url":"https://api.freedompayments.tech/v1/invoices/{invoice_id}/payment","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/invoices/{invoice_id}/payment","returns":"{payment: PaymentPublic, logs: PaymentLogPublic[]}.","keywords":["txid","transaction","confirmations","payment log","mismatch","underpaid","overpaid","debug payment"],"related":["concept.invoice_vs_payment","flow.watch_invoice"],"source":"docs/workflow.md","source_anchor":"payment-status-machine"},{"id":"endpoint.invoice.public_get","kind":"endpoint","title":"Read an invoice publicly (no credentials)","summary":"Same invoice payload without authentication — safe for a buyer's browser or an agent that only has the invoice id / payment link.","auth":"none","when_to_use":"Polling for payment from a buyer-side or untrusted context.","method":"GET","path":"/v1/public/invoices/{invoice_id}","url":"https://api.freedompayments.tech/v1/public/invoices/{invoice_id}","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/public/invoices/{invoice_id}","returns":"InvoicePublic.","keywords":["public invoice","poll payment","buyer status","no auth","expires"],"related":["flow.watch_invoice","endpoint.invoice.payment"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.invoice.simulate","kind":"endpoint","title":"Simulate a paid invoice (testnet demo only)","summary":"Marks the invoice paid as if the chain had confirmed it, running the real settlement path. Allowed only when network=testnet and DEMO_MODE=true.","auth":"merchant_key","when_to_use":"Integration testing and demos.","method":"POST","path":"/v1/invoices/{invoice_id}/simulate","url":"https://api.freedompayments.tech/v1/invoices/{invoice_id}/simulate","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"},{"name":"api_key","in":"query","required":false,"type":"string"},{"name":"x-api-key","in":"header","required":false,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/v1/invoices/{invoice_id}/simulate -H \"X-API-Key: $FP_KEY\"","returns":"Settled InvoicePublic; 403 when demo mode is off.","keywords":["simulate","test payment","demo","fake","sandbox","mock"],"related":["flow.test_payment_without_crypto","endpoint.config.public"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.llms_full","kind":"endpoint","title":"llms-full.txt corpus","summary":"Everything in one text fetch: catalog in markdown plus the merchant, workflow and agent-access documentation.","auth":"none","when_to_use":"One-shot context loading when latency matters more than size.","method":"GET","path":"/llms-full.txt","url":"https://api.freedompayments.tech/llms-full.txt","example":"curl -s https://api.freedompayments.tech/llms-full.txt","returns":"text/plain full corpus.","keywords":["llms-full","full docs","corpus","bulk","context"],"related":["endpoint.llms_txt"],"source":"docs/agent-access.md"},{"id":"endpoint.llms_txt","kind":"endpoint","title":"llms.txt index","summary":"Curated markdown entry point for LLM agents.","auth":"none","when_to_use":"First fetch after discovering the service; small and cheap.","method":"GET","path":"/llms.txt","url":"https://api.freedompayments.tech/llms.txt","example":"curl -s https://api.freedompayments.tech/llms.txt","returns":"text/plain markdown index.","keywords":["llms.txt","agent index","entry point","summary"],"related":["endpoint.llms_full","endpoint.catalog"],"source":"docs/agent-access.md"},{"id":"endpoint.login-detect_login_identity","kind":"endpoint","title":"Detect Login Identity","summary":"Detect auth source from a single identity field (shape-based).","auth":"none","method":"GET","path":"/api/v1/login/identity-source","url":"https://api.freedompayments.tech/api/v1/login/identity-source","params":[{"name":"q","in":"query","required":true,"type":"string"}],"keywords":["login"],"auto":true},{"id":"endpoint.login-recover_password","kind":"endpoint","title":"Recover Password","summary":"Recover Password","auth":"none","method":"POST","path":"/api/v1/password-recovery/{email}","url":"https://api.freedompayments.tech/api/v1/password-recovery/{email}","params":[{"name":"email","in":"path","required":true,"type":"string"}],"keywords":["login"],"auto":true},{"id":"endpoint.login-recover_password_html_content","kind":"endpoint","title":"Recover Password Html Content","summary":"Recover Password Html Content","auth":"jwt","method":"POST","path":"/api/v1/password-recovery-html-content/{email}","url":"https://api.freedompayments.tech/api/v1/password-recovery-html-content/{email}","params":[{"name":"email","in":"path","required":true,"type":"string"}],"keywords":["login"],"auto":true},{"id":"endpoint.login-reset_password","kind":"endpoint","title":"Reset Password","summary":"Reset Password","auth":"none","method":"POST","path":"/api/v1/reset-password/","url":"https://api.freedompayments.tech/api/v1/reset-password/","params":[{"name":"token","in":"body","required":true,"type":"string"},{"name":"new_password","in":"body","required":true,"type":"string"}],"keywords":["login"],"auto":true},{"id":"endpoint.login-test_token","kind":"endpoint","title":"Test Token","summary":"Test Token","auth":"jwt","method":"POST","path":"/api/v1/login/test-token","url":"https://api.freedompayments.tech/api/v1/login/test-token","keywords":["login"],"auto":true},{"id":"endpoint.login.access_token","kind":"endpoint","title":"Log in and get a JWT","summary":"Form-encoded username/password login returning access_token for Authorization: Bearer (merchant and admin alike).","auth":"none","when_to_use":"Obtaining the JWT required by /api/v1/merchant/* routes.","method":"POST","path":"/api/v1/login/access-token","url":"https://api.freedompayments.tech/api/v1/login/access-token","example":"curl -s -X POST https://api.freedompayments.tech/api/v1/login/access-token \\\n  -d \"username=me@example.com&password=changeme123\"","returns":"Token: {access_token, token_type}.","keywords":["login","sign in","token","jwt","authenticate","get token"],"related":["concept.auth","endpoint.merchant.account.get"],"source":"docs/merchant.md","source_anchor":"authenticated-merchant-api"},{"id":"endpoint.login.google","kind":"endpoint","title":"Log in with Google","summary":"Exchange a Google credential for a JWT (enabled when configured).","auth":"none","when_to_use":"Automating a merchant login that has no password.","method":"POST","path":"/api/v1/login/google","url":"https://api.freedompayments.tech/api/v1/login/google","params":[{"name":"id_token","in":"body","required":true,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/api/v1/login/google \\\n  -H \"Content-Type: application/json\" -d '{\"credential\":\"<google_id_token>\"}'","returns":"Token.","keywords":["google login","oauth","social login","sso"],"related":["endpoint.login.access_token","endpoint.config.public"],"source":"README.md","source_anchor":"merchant-flow-base-plan"},{"id":"endpoint.login.telegram","kind":"endpoint","title":"Log in with Telegram","summary":"Exchange Telegram sign-in data for a JWT (enabled when configured).","auth":"none","when_to_use":"Automating a merchant login that has no password.","method":"POST","path":"/api/v1/login/telegram","url":"https://api.freedompayments.tech/api/v1/login/telegram","params":[{"name":"id","in":"body","required":true,"type":"integer"},{"name":"first_name","in":"body","required":false,"type":"string"},{"name":"last_name","in":"body","required":false,"type":"string"},{"name":"username","in":"body","required":false,"type":"string"},{"name":"photo_url","in":"body","required":false,"type":"string"},{"name":"auth_date","in":"body","required":true,"type":"integer"},{"name":"hash","in":"body","required":true,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/api/v1/login/telegram \\\n  -H \"Content-Type: application/json\" -d '{\"id\":123,\"hash\":\"...\",\"auth_date\":1700000000}'","returns":"Token.","keywords":["telegram login","tg auth","social login"],"related":["endpoint.login.access_token"],"source":"README.md","source_anchor":"merchant-flow-base-plan"},{"id":"endpoint.logo","kind":"endpoint","title":"Logo","summary":"The brand mark shown on every buyer surface.","auth":"none","method":"GET","path":"/logo.png","url":"https://api.freedompayments.tech/logo.png","auto":true},{"id":"endpoint.merchant-patch_unit","kind":"endpoint","title":"Patch Unit","summary":"Patch Unit","auth":"jwt","method":"PATCH","path":"/api/v1/merchant/units/{unit_id}","url":"https://api.freedompayments.tech/api/v1/merchant/units/{unit_id}","params":[{"name":"unit_id","in":"path","required":true,"type":"string"},{"name":"title","in":"body","required":false,"type":"string"},{"name":"description","in":"body","required":false,"type":"string"},{"name":"amount_usd","in":"body","required":false,"type":"number"},{"name":"currencies","in":"body","required":false,"type":"string[]"},{"name":"wait_seconds","in":"body","required":false,"type":"integer"},{"name":"language","in":"body","required":false,"type":"string"},{"name":"active","in":"body","required":false,"type":"boolean"}],"keywords":["merchant"],"auto":true},{"id":"endpoint.merchant-payment_page","kind":"endpoint","title":"Payment Page","summary":"Payment Page","auth":"jwt","method":"GET","path":"/api/v1/merchant/payment-page","url":"https://api.freedompayments.tech/api/v1/merchant/payment-page","keywords":["merchant"],"auto":true},{"id":"endpoint.merchant-remove_unit","kind":"endpoint","title":"Remove Unit","summary":"Remove Unit","auth":"jwt","method":"DELETE","path":"/api/v1/merchant/units/{unit_id}","url":"https://api.freedompayments.tech/api/v1/merchant/units/{unit_id}","params":[{"name":"unit_id","in":"path","required":true,"type":"string"}],"keywords":["merchant"],"auto":true},{"id":"endpoint.merchant.account.get","kind":"endpoint","title":"Read my merchant account (slug, API key, webhook, plan)","summary":"Merchant account record: slug, api_key (fp_…), webhook_url and secret, plan limits. This is where an agent gets the merchant key used by the public /v1 invoice routes.","auth":"jwt","when_to_use":"Right after login, to obtain the fp_ key, or to discover the merchant slug used in pretty unit URLs.","method":"GET","path":"/api/v1/merchant/account","url":"https://api.freedompayments.tech/api/v1/merchant/account","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/account -H \"Authorization: Bearer $TOKEN\"","returns":"MerchantAccountPublic including api_key and webhook settings.","keywords":["api key","account","slug","webhook","profile","plan","credentials"],"related":["concept.auth","endpoint.merchant.account.patch"],"source":"docs/merchant.md","source_anchor":"authenticated-merchant-api"},{"id":"endpoint.merchant.account.patch","kind":"endpoint","title":"Update merchant account (slug, webhook)","summary":"Change slug, webhook_url, webhook_secret or enabled settings.","auth":"jwt","when_to_use":"Pointing payment notifications at a shop backend.","method":"PATCH","path":"/api/v1/merchant/account","url":"https://api.freedompayments.tech/api/v1/merchant/account","params":[{"name":"webhook_url","in":"body","required":false,"type":"string"},{"name":"webhook_secret","in":"body","required":false,"type":"string"},{"name":"enabled_currencies","in":"body","required":false,"type":"string[]"}],"example":"curl -s -X PATCH https://api.freedompayments.tech/api/v1/merchant/account \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n  -d '{\"webhook_url\":\"https://shop.example/fp\",\"webhook_secret\":\"s3cret\"}'","returns":"Updated MerchantAccountPublic.","keywords":["webhook","configure","settings","slug","update account"],"related":["endpoint.merchant.account.get","endpoint.merchant.income"],"source":"docs/merchant.md","source_anchor":"webhook--income"},{"id":"endpoint.merchant.balances","kind":"endpoint","title":"Read prepaid balances and remaining limit","summary":"Per-currency balances plus limit_of_payments.","auth":"jwt","when_to_use":"Before expecting payments: a merchant with no remaining limit will not be observed (see concept.prepaid_limit).","method":"GET","path":"/api/v1/merchant/balances","url":"https://api.freedompayments.tech/api/v1/merchant/balances","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/balances -H \"Authorization: Bearer $TOKEN\"","returns":"BalancePublic[] with amount, limit_of_payments.","keywords":["balance","prepaid","limit","funds","how much left"],"related":["flow.refill_prepaid","concept.prepaid_limit"],"source":"docs/merchant.md","source_anchor":"prepaid-balance--payment-limit"},{"id":"endpoint.merchant.embed_preview","kind":"endpoint","title":"Embed snippets and how-it-works payload","summary":"Ready-made embed snippets for the merchant account.","auth":"jwt","when_to_use":"Generating integration code for a merchant without composing it.","method":"GET","path":"/api/v1/merchant/embed-preview","url":"https://api.freedompayments.tech/api/v1/merchant/embed-preview","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/embed-preview -H \"Authorization: Bearer $TOKEN\"","returns":"Snippets + explanation payload.","keywords":["embed preview","snippets","integration code","copy paste"],"related":["flow.embed_checkout","concept.surfaces"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"endpoint.merchant.income","kind":"endpoint","title":"Income history (confirmed payments)","summary":"Confirmed payments with fee, txid, webhook status, date filters and pagination.","auth":"jwt","when_to_use":"Accounting, reconciliation and 'did the money arrive' reports.","method":"GET","path":"/api/v1/merchant/income","url":"https://api.freedompayments.tech/api/v1/merchant/income","params":[{"name":"skip","in":"query","required":false,"type":"integer"},{"name":"limit","in":"query","required":false,"type":"integer"},{"name":"from_date","in":"query","required":false,"type":"string","description":"YYYY-MM-DD (UTC). Filter created_at >= from_date"},{"name":"to_date","in":"query","required":false,"type":"string","description":"YYYY-MM-DD (UTC). Filter created_at <= to_date"}],"example":"curl -s https://api.freedompayments.tech/api/v1/merchant/income -H \"Authorization: Bearer $TOKEN\"","returns":"IncomeHistoryPublic: items[] + pagination.","keywords":["income","history","revenue","settled payments","accounting","report"],"related":["endpoint.merchant.account.patch","concept.fees"],"source":"docs/merchant.md","source_anchor":"webhook--income"},{"id":"endpoint.merchant.refill","kind":"endpoint","title":"Create a refill (top-up) invoice","summary":"Creates an invoice whose payment credits the prepaid balance (multiplier REFILL_CREDIT_MULTIPLIER, default ×100).","auth":"jwt","when_to_use":"Funding a merchant so observers will watch their payments.","method":"POST","path":"/api/v1/merchant/refill","url":"https://api.freedompayments.tech/api/v1/merchant/refill","params":[{"name":"chain","in":"body","required":true,"type":"string"},{"name":"amount","in":"body","required":true,"type":"number"},{"name":"amount_unit","in":"body","required":false,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/api/v1/merchant/refill \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n  -d '{\"chain\":\"ton\",\"amount_usd\":\"10\"}'","returns":"Refill InvoicePublic to pay.","keywords":["refill","top up","deposit","add funds","credit balance"],"related":["flow.refill_prepaid","endpoint.merchant.balances"],"source":"docs/merchant.md","source_anchor":"prepaid-balance--payment-limit"},{"id":"endpoint.merchant.refill_wallets","kind":"endpoint","title":"Platform refill wallets","summary":"Addresses a merchant pays to top up the prepaid balance.","auth":"jwt","when_to_use":"Showing where to send the refill payment.","method":"GET","path":"/api/v1/merchant/refill-wallets","url":"https://api.freedompayments.tech/api/v1/merchant/refill-wallets","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/refill-wallets -H \"Authorization: Bearer $TOKEN\"","returns":"Refill wallet list per chain.","keywords":["refill wallet","top up address","deposit address"],"related":["flow.refill_prepaid"],"source":"docs/merchant.md","source_anchor":"prepaid-balance--payment-limit"},{"id":"endpoint.merchant.units.create","kind":"endpoint","title":"Create a payment unit","summary":"Create one sellable offer: title, description, USD price, accepted currencies (each needs prepaid + wallet) and wait time. Base plan: at most BASE_MAX_PAYMENT_UNITS (default 3).","auth":"jwt","when_to_use":"Turning 'what I sell' into something embeddable and chargeable.","method":"POST","path":"/api/v1/merchant/units","url":"https://api.freedompayments.tech/api/v1/merchant/units","params":[{"name":"title","in":"body","required":true,"type":"str"},{"name":"amount_usd","in":"body","required":true,"type":"decimal"},{"name":"currencies","in":"body","required":true,"type":"str[]"},{"name":"wait_seconds","in":"body","required":false,"type":"int","description":"Clamped to UNIT_WAIT_SECONDS_MIN…MAX (300–86400)."},{"name":"description","in":"body","required":false,"type":"str"}],"example":"curl -s -X POST https://api.freedompayments.tech/api/v1/merchant/units \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"Coffee\",\"description\":\"One cup\",\"amount_usd\":4.5,\"currencies\":[\"ton\"],\"wait_seconds\":1800}'","returns":"Unit object with page_url and embed URLs.","keywords":["create unit","add product","new offer","sell item","goods","price","listing"],"related":["flow.sell_unit","endpoint.merchant.units.list","flow.embed_checkout"],"source":"docs/merchant.md","source_anchor":"create-unit-example"},{"id":"endpoint.merchant.units.list","kind":"endpoint","title":"List my units with limits and available currencies","summary":"All units plus max_payment_units, available_currencies and the wait time window.","auth":"jwt","when_to_use":"Deciding whether a new unit fits the plan, or finding a unit id.","method":"GET","path":"/api/v1/merchant/units","url":"https://api.freedompayments.tech/api/v1/merchant/units","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/units -H \"Authorization: Bearer $TOKEN\"","returns":"{units: [...], max_payment_units, available_currencies, wait_* }","keywords":["my units","list products","offers","catalog","find unit"],"related":["endpoint.merchant.units.create","endpoint.unit.get"],"source":"docs/merchant.md","source_anchor":"authenticated-merchant-api"},{"id":"endpoint.merchant.wallets.get","kind":"endpoint","title":"List my receive wallets","summary":"Addresses configured per chain, with what is still missing.","auth":"jwt","when_to_use":"Checking readiness before creating or publishing a unit.","method":"GET","path":"/api/v1/merchant/wallets","url":"https://api.freedompayments.tech/api/v1/merchant/wallets","example":"curl -s https://api.freedompayments.tech/api/v1/merchant/wallets -H \"Authorization: Bearer $TOKEN\"","returns":"{wallets: [...]}","keywords":["wallets","addresses","configured","list wallets"],"related":["endpoint.merchant.wallets.put"],"source":"docs/merchant.md","source_anchor":"non-custodial-wallets"},{"id":"endpoint.merchant.wallets.put","kind":"endpoint","title":"Set a non-custodial receive wallet","summary":"Store the merchant's own receive address for one chain.","auth":"jwt","when_to_use":"Before a currency can be enabled on a unit.","method":"PUT","path":"/api/v1/merchant/wallets","url":"https://api.freedompayments.tech/api/v1/merchant/wallets","params":[{"name":"blockchain","in":"body","required":true,"type":"string"},{"name":"address","in":"body","required":true,"type":"string"}],"example":"curl -s -X PUT https://api.freedompayments.tech/api/v1/merchant/wallets \\\n  -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n  -d '{\"chain\":\"ton\",\"address\":\"EQ...\"}'","returns":"Stored wallet entry per chain.","keywords":["wallet","receive address","non-custodial","where to receive","set address"],"related":["concept.non_custodial","endpoint.merchant.wallets.get"],"source":"docs/merchant.md","source_anchor":"non-custodial-wallets"},{"id":"endpoint.openapi","kind":"endpoint","title":"OpenAPI schema (authoritative types)","summary":"Generated OpenAPI 3 document for every route — use it for exact schemas; use the catalog for goals and examples.","auth":"none","when_to_use":"Validating payloads or generating a client.","method":"GET","path":"/api/v1/openapi.json","url":"https://api.freedompayments.tech/api/v1/openapi.json","example":"curl -s https://api.freedompayments.tech/api/v1/openapi.json","returns":"OpenAPI 3.1 JSON.","keywords":["openapi","swagger","schema","types","spec","client"],"related":["endpoint.catalog"],"source":"README.md"},{"id":"endpoint.pay.div","kind":"endpoint","title":"Invoice pay widget fragment (HTML)","summary":"CORS-open HTML fragment for embedding an existing invoice; size=mobile|desktop.","auth":"none","when_to_use":"Embed an invoice you created via the API into your own page.","method":"GET","path":"/v1/pay/{invoice_id}/div","url":"https://api.freedompayments.tech/v1/pay/{invoice_id}/div","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"},{"name":"size","in":"query","required":false,"type":"enum(sm|md|lg|mobile|desktop|site|phone|page|url)","enum":["sm","md","lg","mobile","desktop","site","phone","page","url"]},{"name":"width","in":"query","required":false,"type":"integer"}],"example":"curl -s https://api.freedompayments.tech/v1/pay/{invoice_id}/div?size=mobile","returns":"text/html fragment with Access-Control-Allow-Origin: *","keywords":["embed invoice","widget","div","fragment","iframe"],"related":["endpoint.pay.page","flow.embed_checkout"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"endpoint.pay.page","kind":"endpoint","title":"Invoice checkout page (HTML)","summary":"Server-rendered pay page with QR, address, amount and memo. size=mobile|desktop|site.","auth":"none","when_to_use":"Show a human (or a browser-capable agent) how to pay.","method":"GET","path":"/v1/pay/{invoice_id}/page","url":"https://api.freedompayments.tech/v1/pay/{invoice_id}/page","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"},{"name":"size","in":"query","required":false,"type":"enum(sm|md|lg|mobile|desktop|site|phone|page|url)","enum":["sm","md","lg","mobile","desktop","site","phone","page","url"]},{"name":"width","in":"query","required":false,"type":"integer"}],"example":"curl -s https://api.freedompayments.tech/v1/pay/{invoice_id}/page?size=desktop","returns":"text/html","keywords":["pay page","checkout page","qr","html","show payment"],"related":["endpoint.pay.div","endpoint.pay.qr"],"source":"docs/merchant.md","source_anchor":"public-urls-per-unit"},{"id":"endpoint.pay.qr","kind":"endpoint","title":"Invoice QR code (SVG)","summary":"QR image for the payment payload — useful in a chat or terminal.","auth":"none","when_to_use":"Rendering the payment request anywhere a QR is easier than text.","method":"GET","path":"/v1/pay/{invoice_id}/qr.svg","url":"https://api.freedompayments.tech/v1/pay/{invoice_id}/qr.svg","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/pay/{invoice_id}/qr.svg -o pay.svg","returns":"image/svg+xml","keywords":["qr","qr code","svg","scan","image"],"related":["endpoint.pay.page","endpoint.pay.qr_png"],"source":"docs/merchant.md","source_anchor":"public-urls-per-unit"},{"id":"endpoint.pay.qr_png","kind":"endpoint","title":"Invoice QR code (PNG, for chats)","summary":"Raster twin of the SVG QR (392×392, image/png, no auth). Chat surfaces need it because Telegram's sendPhoto rejects SVG — this is what InvoicePublic.qr_png_url points at.","auth":"none","when_to_use":"Posting the payment QR into a Telegram/chat message, or anywhere SVG cannot be rendered or resized.","method":"GET","path":"/v1/pay/{invoice_id}/qr.png","url":"https://api.freedompayments.tech/v1/pay/{invoice_id}/qr.png","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/pay/{invoice_id}/qr.png -o pay.png","returns":"image/png (same qr_payload as the SVG twin).","keywords":["qr png","qr photo","telegram","sendphoto","raster","chat","image"],"related":["endpoint.pay.qr","flow.accept_payment_telegram"],"source":"docs/quickstart-telegram-bot.md","source_anchor":"4-show-requisites-and-the-qr-photo"},{"id":"endpoint.pay_page","kind":"endpoint","title":"Pay Page","summary":"Prefer server-rendered checkout (QR + copy fields).","auth":"none","method":"GET","path":"/pay/{invoice_id}","url":"https://api.freedompayments.tech/pay/{invoice_id}","params":[{"name":"invoice_id","in":"path","required":true,"type":"string"}],"auto":true},{"id":"endpoint.robots","kind":"endpoint","title":"robots.txt","summary":"Crawl rules for the API origin plus pointers to sitemap and llms.txt.","auth":"none","when_to_use":"Respecting crawl policy while discovering the service.","method":"GET","path":"/robots.txt","url":"https://api.freedompayments.tech/robots.txt","example":"curl -s https://api.freedompayments.tech/robots.txt","returns":"text/plain","keywords":["robots","crawl","policy","disallow"],"related":["endpoint.sitemap","endpoint.llms_txt"],"source":"docs/agent-access.md"},{"id":"endpoint.search","kind":"endpoint","title":"Search this service by intent","summary":"Lexical search over the capability catalog and the documentation. Query in natural language — for example \"create an invoice\", \"refill limit\" or \"embed a buy button\" — and get ranked hits, each with a ready-to-run call.","auth":"none","when_to_use":"First call for any task against this service when you do not already know the capability id.","method":"GET","path":"/v1/search","url":"https://api.freedompayments.tech/v1/search","params":[{"name":"q","in":"query","required":true,"type":"str"},{"name":"limit","in":"query","required":false,"type":"int"},{"name":"kind","in":"query","required":false,"type":"enum(flow|endpoint|page|embed|concept|guide)"},{"name":"include_docs","in":"query","required":false,"type":"bool","description":"Include markdown doc sections (default true)."}],"example":"curl -s \"https://api.freedompayments.tech/v1/search?q=create%20an%20invoice&limit=5\"","returns":"{query, count, results:[{id, kind, title, score, snippet, call}]}","keywords":["search","find","how do i","lookup","query","discover","help"],"related":["endpoint.catalog","endpoint.llms_txt"],"source":"docs/agent-access.md"},{"id":"endpoint.sitemap","kind":"endpoint","title":"Sitemap (surfaces + live units)","summary":"XML sitemap of public pages plus every active merchant unit's pretty page and API page.","auth":"none","when_to_use":"Crawling everything that is publicly sellable.","method":"GET","path":"/sitemap.xml","url":"https://api.freedompayments.tech/sitemap.xml","example":"curl -s https://api.freedompayments.tech/sitemap.xml","returns":"application/xml sitemap.","keywords":["sitemap","crawl","urls","pages","seo"],"related":["page.sell_info","endpoint.unit.pretty_page"],"source":"docs/agent-access.md"},{"id":"endpoint.unit.checkout","kind":"endpoint","title":"Create an invoice from a unit","summary":"The correct way to charge for a unit: pick a chain from the unit's currencies and this creates an invoice with the unit's price, owner, wait time and webhook.","auth":"none","when_to_use":"Any buyer-side purchase of one of the merchant's offers.","method":"POST","path":"/v1/units/{unit_id}/checkout","url":"https://api.freedompayments.tech/v1/units/{unit_id}/checkout","params":[{"name":"chain","in":"body","required":true,"type":"str"},{"name":"external_ref","in":"body","required":false,"type":"str"}],"example":"curl -s -X POST https://api.freedompayments.tech/v1/units/{unit_id}/checkout \\\n  -H \"Content-Type: application/json\" -d '{\"chain\":\"ton\",\"external_ref\":\"order-42\"}'","returns":"InvoicePublic for the new invoice.","keywords":["checkout","buy unit","purchase","order","charge for offer","create invoice from unit"],"related":["flow.accept_payment","endpoint.unit.get","endpoint.pay.page"],"source":"docs/merchant.md","source_anchor":"public--merchant-key-payment-api"},{"id":"endpoint.unit.div","kind":"endpoint","title":"Unit chooser embed (HTML fragment)","summary":"Embeddable unit chooser: buyer picks a currency and checkout is created automatically. size=mobile|desktop.","auth":"none","when_to_use":"'Add a buy button/checkout to my site' with zero client code.","method":"GET","path":"/v1/units/{unit_id}/div","url":"https://api.freedompayments.tech/v1/units/{unit_id}/div","params":[{"name":"unit_id","in":"path","required":true,"type":"string"},{"name":"size","in":"query","required":false,"type":"enum(sm|md|lg|mobile|desktop|site|phone|page|url)","enum":["sm","md","lg","mobile","desktop","site","phone","page","url"]}],"example":"curl -s https://api.freedompayments.tech/v1/units/{unit_id}/div?size=mobile","returns":"text/html fragment with Access-Control-Allow-Origin: *","keywords":["embed","buy button","widget","div","iframe","mobile","desktop"],"related":["flow.embed_checkout","concept.surfaces"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"endpoint.unit.get","kind":"endpoint","title":"Read a payment unit","summary":"Public metadata for a unit: title, description, USD price, accepted currencies, wait time, page/embed URLs and surfaces.","auth":"none","when_to_use":"Before checkout, to show the buyer what they are buying.","method":"GET","path":"/v1/units/{unit_id}","url":"https://api.freedompayments.tech/v1/units/{unit_id}","params":[{"name":"unit_id","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/v1/units/{unit_id}","returns":"Unit object with currencies[], surfaces[], page_url, embed URLs.","keywords":["unit","offer","product","price","goods","metadata"],"related":["endpoint.unit.checkout","flow.accept_payment"],"source":"docs/merchant.md","source_anchor":"payment-unit"},{"id":"endpoint.unit.page","kind":"endpoint","title":"Unit chooser page (HTML)","summary":"Full page version of the unit chooser; ?size=site is the default.","auth":"none","when_to_use":"A shareable link a human can open.","method":"GET","path":"/v1/units/{unit_id}/page","url":"https://api.freedompayments.tech/v1/units/{unit_id}/page","params":[{"name":"unit_id","in":"path","required":true,"type":"string"},{"name":"size","in":"query","required":false,"type":"enum(sm|md|lg|mobile|desktop|site|phone|page|url)","enum":["sm","md","lg","mobile","desktop","site","phone","page","url"]}],"example":"curl -s https://api.freedompayments.tech/v1/units/{unit_id}/page","returns":"text/html","keywords":["unit page","share link","html","site"],"related":["endpoint.unit.pretty_page"],"source":"docs/merchant.md","source_anchor":"public-urls-per-unit"},{"id":"endpoint.unit.pretty_page","kind":"endpoint","title":"Pretty unit page by slugs","summary":"Human-friendly /u/{merchant_slug}/{unit_slug} page for a unit.","auth":"none","when_to_use":"Sharing a memorable link instead of a UUID URL.","method":"GET","path":"/u/{merchant_slug}/{unit_slug}","url":"https://api.freedompayments.tech/u/{merchant_slug}/{unit_slug}","params":[{"name":"merchant_slug","in":"path","required":true,"type":"string"},{"name":"unit_slug","in":"path","required":true,"type":"string"}],"example":"curl -s https://api.freedompayments.tech/u/{merchant_slug}/{unit_slug}","returns":"text/html","keywords":["pretty url","slug","share","link","page"],"related":["endpoint.unit.page"],"source":"docs/merchant.md","source_anchor":"public-urls-per-unit"},{"id":"endpoint.users-create_user","kind":"endpoint","title":"Create User","summary":"Create new user.","auth":"jwt","method":"POST","path":"/api/v1/users/","url":"https://api.freedompayments.tech/api/v1/users/","params":[{"name":"email","in":"body","required":true,"type":"string"},{"name":"is_active","in":"body","required":false,"type":"boolean"},{"name":"is_superuser","in":"body","required":false,"type":"boolean"},{"name":"full_name","in":"body","required":false,"type":"string"},{"name":"password","in":"body","required":true,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-delete_user","kind":"endpoint","title":"Delete User","summary":"Delete a user.","auth":"jwt","method":"DELETE","path":"/api/v1/users/{user_id}","url":"https://api.freedompayments.tech/api/v1/users/{user_id}","params":[{"name":"user_id","in":"path","required":true,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-delete_user_me","kind":"endpoint","title":"Delete User Me","summary":"Delete own user.","auth":"jwt","method":"DELETE","path":"/api/v1/users/me","url":"https://api.freedompayments.tech/api/v1/users/me","keywords":["users"],"auto":true},{"id":"endpoint.users-read_user_by_id","kind":"endpoint","title":"Read User By Id","summary":"Get a specific user by id.","auth":"jwt","method":"GET","path":"/api/v1/users/{user_id}","url":"https://api.freedompayments.tech/api/v1/users/{user_id}","params":[{"name":"user_id","in":"path","required":true,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-read_user_me","kind":"endpoint","title":"Read User Me","summary":"Get current user.","auth":"jwt","method":"GET","path":"/api/v1/users/me","url":"https://api.freedompayments.tech/api/v1/users/me","keywords":["users"],"auto":true},{"id":"endpoint.users-read_users","kind":"endpoint","title":"Read Users","summary":"Retrieve users.","auth":"jwt","method":"GET","path":"/api/v1/users/","url":"https://api.freedompayments.tech/api/v1/users/","params":[{"name":"skip","in":"query","required":false,"type":"integer"},{"name":"limit","in":"query","required":false,"type":"integer"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-update_password_me","kind":"endpoint","title":"Update Password Me","summary":"Update own password.","auth":"jwt","method":"PATCH","path":"/api/v1/users/me/password","url":"https://api.freedompayments.tech/api/v1/users/me/password","params":[{"name":"current_password","in":"body","required":true,"type":"string"},{"name":"new_password","in":"body","required":true,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-update_user","kind":"endpoint","title":"Update User","summary":"Update a user.","auth":"jwt","method":"PATCH","path":"/api/v1/users/{user_id}","url":"https://api.freedompayments.tech/api/v1/users/{user_id}","params":[{"name":"user_id","in":"path","required":true,"type":"string"},{"name":"email","in":"body","required":false,"type":"string"},{"name":"is_active","in":"body","required":false,"type":"boolean"},{"name":"is_superuser","in":"body","required":false,"type":"boolean"},{"name":"full_name","in":"body","required":false,"type":"string"},{"name":"password","in":"body","required":false,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users-update_user_me","kind":"endpoint","title":"Update User Me","summary":"Update own user.","auth":"jwt","method":"PATCH","path":"/api/v1/users/me","url":"https://api.freedompayments.tech/api/v1/users/me","params":[{"name":"full_name","in":"body","required":false,"type":"string"},{"name":"email","in":"body","required":false,"type":"string"}],"keywords":["users"],"auto":true},{"id":"endpoint.users.signup","kind":"endpoint","title":"Register a merchant account","summary":"Create a user/merchant account with email + password.","auth":"none","when_to_use":"First step of flow.sell_unit when there is no account yet.","method":"POST","path":"/api/v1/users/signup","url":"https://api.freedompayments.tech/api/v1/users/signup","params":[{"name":"email","in":"body","required":true,"type":"string"},{"name":"password","in":"body","required":true,"type":"string"},{"name":"full_name","in":"body","required":false,"type":"string"}],"example":"curl -s -X POST https://api.freedompayments.tech/api/v1/users/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"me@example.com\",\"password\":\"changeme123\"}'","returns":"UserPublic.","keywords":["signup","register","create account","new merchant","onboard"],"related":["endpoint.login.access_token","flow.sell_unit"],"source":"README.md","source_anchor":"merchant-flow-base-plan"},{"id":"endpoint.utils-health_check","kind":"endpoint","title":"Health Check","summary":"Health Check","auth":"none","method":"GET","path":"/api/v1/utils/health-check/","url":"https://api.freedompayments.tech/api/v1/utils/health-check/","keywords":["utils"],"auto":true},{"id":"endpoint.utils-test_email","kind":"endpoint","title":"Test Email","summary":"Test emails.","auth":"jwt","method":"POST","path":"/api/v1/utils/test-email/","url":"https://api.freedompayments.tech/api/v1/utils/test-email/","params":[{"name":"email_to","in":"query","required":true,"type":"string"}],"keywords":["utils"],"auto":true},{"id":"page.ai_friendly","kind":"page","title":"AI-friendly policy page","summary":"The operator's public stance: agents are first-class clients, no CAPTCHA or browser-only gates, no KYC/AML identity walls, high-IQ entities welcome. Non-custodial, so funds never sit with the platform.","auth":"none","when_to_use":"Read this when you need to know whether this service is meant to be used by autonomous agents — it is, explicitly.","path":"/ai-friendly","url":"https://api.freedompayments.tech/ai-friendly","keywords":["ai friendly","ai-friendly","agents welcome","no kyc","kyc","aml","policy","values","manifesto","freedom","captcha"],"related":["guide.ai_friendly","concept.overview","endpoint.search"],"source":"docs/ai-friendly.md"},{"id":"page.docs","kind":"page","title":"Swagger UI (interactive API reference)","summary":"Swagger UI at /docs for the whole API, backed by the generated OpenAPI document. ReDoc is available at /redoc.","auth":"none","when_to_use":"A human wants to try calls by hand. Agents should fetch /api/v1/openapi.json or /v1/catalog instead — HTML is not needed.","path":"/docs","url":"https://api.freedompayments.tech/docs","keywords":["swagger","docs","api reference","try it out","redoc"],"related":["endpoint.openapi","endpoint.catalog"],"source":"README.md"},{"id":"page.guide","kind":"page","title":"New-merchant guide (zero to first payment)","summary":"Step-by-step instructions for a merchant with no crypto background: create an account, get a wallet, save the address, create a product, top up the prepaid balance, pay yourself a test dollar, share the link. Includes the five mistakes that cost money and a checklist.","auth":"none","when_to_use":"A human asks how to start, or an agent needs the same order of operations in prose before automating them. Agents should still call the endpoints in this catalog rather than follow the page.","path":"/guide","url":"https://api.freedompayments.tech/guide","keywords":["guide","getting started","onboarding","first payment","tutorial","instructions","how to start"],"related":["page.workflow","flow.sell_unit","flow.refill_prepaid"],"source":"docs/roadmap.md"},{"id":"page.manage","kind":"page","title":"Client workspace (SPA, requires login)","summary":"React workspace at /manage/*: dashboard, payment units, wallets, limits, payment history and account settings. This is the human UI for exactly the same operations the merchant API exposes.","auth":"jwt","when_to_use":"Human UI only. Agents should prefer the API endpoints in this catalog — the SPA renders client-side and exposes no data in HTML.","path":"/manage","url":"https://api.freedompayments.tech/manage","keywords":["dashboard","workspace","client area","settings page","merchant ui","manage"],"related":["page.sell_info","endpoint.merchant.account.get"],"source":"docs/merchant.md","source_anchor":"backoffice"},{"id":"page.sell_info","kind":"page","title":"Public sell page (merchant-facing landing)","summary":"Product landing: what it does, how selling works, supported currencies, the three checkout surfaces, sign-up/login panel.","auth":"none","when_to_use":"A human or browser agent needs the product overview.","path":"/","url":"https://api.freedompayments.tech/","keywords":["landing","homepage","product page","sign up","marketing"],"related":["concept.overview","page.workflow"],"source":"README.md"},{"id":"page.workflow","kind":"page","title":"Interactive workflow demo page","summary":"Walkthrough of the whole lifecycle (refill → unit → checkout → observe → settle) with the stage names used in docs/workflow.md.","auth":"none","when_to_use":"Explaining or verifying the flow before automating it.","path":"/workflow","url":"https://api.freedompayments.tech/workflow","keywords":["workflow","demo","lifecycle","stages","walkthrough"],"related":["flow.sell_unit","flow.accept_payment"],"source":"docs/workflow.md"},{"id":"embed.invoice","kind":"embed","title":"Existing-invoice embed","summary":"Embed a specific invoice you already created through the API (data-invoice instead of data-unit) — used after checkout or for order-status pages.","auth":"none","when_to_use":"You created the invoice server-side and want the payment UI inside your own order page.","example":"<div id=\"freedompayments-pay\"></div>\n<script src=\"https://api.freedompayments.tech/embed.js\" data-invoice=\"{invoice_id}\"\n        data-target=\"#freedompayments-pay\" async></script>","returns":"The invoice pay UI (QR, address, memo) inside your page.","keywords":["invoice embed","pay widget","existing invoice","order page","embed.js"],"related":["embed.unit.mobile","endpoint.pay.div","endpoint.invoice.create"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"embed.unit.desktop","kind":"embed","title":"Desktop embed — wide unit checkout","summary":"Same snippet with data-size=\"desktop\": wide layout with the QR beside wallet, amount and memo.","auth":"none","when_to_use":"A desktop website or dashboard needs an inline checkout block.","example":"<div id=\"fp-unit-coffee-desktop\"></div>\n<script src=\"https://api.freedompayments.tech/embed.js\" data-unit=\"{unit_id}\"\n        data-size=\"desktop\" data-target=\"#fp-unit-coffee-desktop\" async></script>","returns":"A mounted checkout that creates invoices on demand.","keywords":["desktop embed","big embed","wide","buy button","embed.js","qr beside"],"related":["embed.unit.mobile","concept.surfaces","flow.embed_checkout"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"embed.unit.mobile","kind":"embed","title":"Mobile embed — phone-first unit checkout","summary":"Drop-in snippet: embed.js mounts the unit chooser into your own div with the compact mobile layout (full-width column, large tap targets, small QR).","auth":"none","when_to_use":"A mobile site, webview or responsive app needs a buy button.","example":"<div id=\"fp-unit-coffee-mobile\"></div>\n<script src=\"https://api.freedompayments.tech/embed.js\" data-unit=\"{unit_id}\"\n        data-size=\"mobile\" data-target=\"#fp-unit-coffee-mobile\" async></script>","returns":"A mounted checkout that creates invoices on demand.","keywords":["mobile embed","phone","small embed","buy button","embed.js","responsive"],"related":["embed.unit.desktop","concept.surfaces","flow.embed_checkout"],"source":"docs/merchant.md","source_anchor":"embed-snippets"},{"id":"concept.auth","kind":"concept","title":"Authentication model","summary":"Three independent credentials: (1) public routes need nothing, (2) merchant API key fp_… in X-API-Key for /v1 invoice routes, (3) JWT bearer token for /api/v1 merchant and admin routes.","auth":"none","when_to_use":"Before calling anything authenticated: pick the credential from the `auth` field of the capability you want, then see endpoint.login.* or endpoint.merchant.account.get to obtain it.","keywords":["auth","authentication","api key","x-api-key","bearer","jwt","token","credentials","login"],"related":["endpoint.login.access_token","endpoint.merchant.account.get","endpoint.invoice.create"],"source":"docs/merchant.md"},{"id":"concept.fees","kind":"concept","title":"Fees","summary":"PLATFORM_FEE_RATE (default 1%) is taken from the merchant prepaid balance on each confirmed payment. SERVICE_FEE_PERCENT (default 0) is an optional surcharge added to the payer's total.","auth":"none","when_to_use":"When computing or explaining what a merchant nets.","keywords":["fee","fees","commission","1%","pricing","net amount"],"related":["concept.prepaid_limit","endpoint.config.public"],"source":"docs/merchant.md","source_anchor":"webhook--income"},{"id":"concept.invoice_vs_payment","kind":"concept","title":"Invoice vs Payment","summary":"An Invoice is what the buyer sees (address, memo, amount, expiry). A Payment is the on-chain observation attached to it (status, txid, confirmations, amount_match).","auth":"none","when_to_use":"When reasoning about status: poll the invoice for a single state string, or read the payment when you need txid/confirmations/logs.","keywords":["invoice","payment","status","txid","confirmations","state machine","difference"],"related":["endpoint.invoice.get","endpoint.invoice.payment"],"source":"docs/workflow.md","source_anchor":"why-split-invoice-and-payment"},{"id":"concept.non_custodial","kind":"concept","title":"Non-custodial wallets","summary":"The merchant pastes one receive address per blockchain; invoices for that chain pay into that address. The platform never holds customer funds — it only observes the chain and matches memo/amount.","auth":"none","when_to_use":"When explaining where money goes, or when a merchant must add or change a receive address before a currency can be enabled.","keywords":["non-custodial","wallet","receive address","self-custody","where do funds go"],"related":["endpoint.merchant.wallets.put"],"source":"docs/merchant.md","source_anchor":"non-custodial-wallets"},{"id":"concept.overview","kind":"concept","title":"What FreedomPayments is","summary":"Non-custodial crypto payment gateway for merchants. A merchant creates payment units (one offer: title, USD price, currencies, wait time), embeds or shares a checkout surface, and buyers pay on-chain straight into the merchant's own wallets. The platform watches the chain, confirms the payment, posts a webhook and debits a prepaid service balance for the fee.","auth":"none","when_to_use":"Read this first when a task involves accepting crypto payments, creating a checkout for a merchant, or checking whether a crypto payment arrived.","keywords":["overview","what is this","crypto payment gateway","merchant","accept crypto","checkout","introduction"],"related":["flow.sell_unit","flow.accept_payment","guide.how_it_works","endpoint.gateways.list"],"source":"README.md","source_anchor":"how-it-works"},{"id":"concept.prepaid_limit","kind":"concept","title":"Prepaid balance and the observation gate","summary":"Merchants top up a prepaid balance; paying sum S credits limit_of_payments += S × 100 (REFILL_CREDIT_MULTIPLIER). Each confirmed payment debits the platform fee (1% by default). An observer only watches a merchant payment while remaining limit ≥ the invoice USD volume, otherwise /check answers HTTP 402.","auth":"none","when_to_use":"Whenever a payment is not being observed, or /check returns 402: the merchant must refill first (flow.refill_prepaid).","keywords":["prepaid","balance","limit","limit_of_payments","top up","refill","402","insufficient","fee","gate"],"related":["flow.refill_prepaid","endpoint.merchant.balances"],"source":"docs/merchant.md","source_anchor":"prepaid-balance--payment-limit"},{"id":"concept.surfaces","kind":"concept","title":"Checkout surfaces (Mobile / Desktop / Site)","summary":"Every unit can be presented three ways: Mobile embed (/v1/units/{id}/div?size=mobile), Desktop embed (?size=desktop), and Site page (/u/{merchant}/{unit} or /v1/units/{id}/page?size=site). Invoice checkout has the same shapes under /v1/pay/{invoice_id}/…","auth":"none","when_to_use":"When a task says 'put a buy button on my site/app', choose a surface here, then copy the snippet from flow.embed_checkout.","keywords":["embed","surface","mobile","desktop","site","iframe","widget","buy button","div"],"related":["flow.embed_checkout","endpoint.unit.div","endpoint.unit.page"],"source":"docs/merchant.md","source_anchor":"public-urls-per-unit"},{"id":"guide.agent_access","kind":"guide","title":"Agent access guide","summary":"How this machine-readable surface is designed, how to search it, and how to extend the catalog.","auth":"none","when_to_use":"Understanding or maintaining agent discoverability itself.","keywords":["agent","llms.txt","catalog","search","discovery","mcp"],"related":["endpoint.catalog","endpoint.search"],"source":"docs/agent-access.md"},{"id":"guide.ai_friendly","kind":"guide","title":"AI-friendly policy (agents are first-class clients)","summary":"The operator's stance in full: agents are welcome as first-class clients, there are no CAPTCHA or browser-only gates, no KYC/AML identity walls, and no compliance queue. Also states what the policy does not mean (the platform is non-custodial and never holds funds).","auth":"none","when_to_use":"When a task depends on whether an autonomous agent is allowed to use this service without a human identity.","keywords":["ai friendly","ai-friendly","agents welcome","no kyc","kyc","aml","identity","captcha","policy","manifesto","freedom","one man army"],"related":["page.ai_friendly","concept.overview","endpoint.search"],"source":"docs/ai-friendly.md"},{"id":"guide.how_it_works","kind":"guide","title":"How a crypto payment works, end to end","summary":"The whole path on one page: a sequence diagram, six steps (unit → invoice → requisites → on-chain payment → confirmation → delivery), a table of every InvoicePublic field, the paid/not-paid status buckets, and why the webhook must be backed by polling.","auth":"none","when_to_use":"First document to read when you need the end-to-end picture before writing any integration code.","keywords":["how it works","end to end","overview","flow","sequence","paid","not paid","status meaning","field meaning","webhook not retried"],"related":["concept.invoice_vs_payment","flow.accept_payment","flow.accept_payment_telegram","guide.quickstart_telegram_bot"],"source":"docs/how-it-works.md"},{"id":"guide.merchant","kind":"guide","title":"Merchant product guide","summary":"Units, prepaid math, non-custodial wallets, webhook payload, embed snippets, full API tables and config reference.","auth":"none","when_to_use":"Authoritative product + API reference for merchants.","keywords":["docs","reference","merchant guide","api table","webhook payload"],"related":["concept.overview","endpoint.invoice.create"],"source":"docs/merchant.md"},{"id":"guide.quickstart_telegram_bot","kind":"guide","title":"Quickstart: crypto payments in a Telegram bot","summary":"A 15-minute recipe with copy-paste code: enable prepaid/currency/wallet, read GET /v1/gateways, POST /v1/invoices with external_ref, send the QR PNG via sendPhoto, accept both webhook branches or poll, and deliver once. Includes an aiohttp client, an error table and the chat-specific gotchas.","auth":"none","when_to_use":"Building a Telegram bot, mini-app or chat integration, or when a payment fails with 400/401/402/403 and you need the fix.","keywords":["telegram","bot","quickstart","tutorial","aiohttp","sendphoto","qr png","not retried","errors","gotchas","idempotent","deliver once"],"related":["flow.accept_payment_telegram","endpoint.pay.qr_png","endpoint.invoice.create","guide.how_it_works"],"source":"docs/quickstart-telegram-bot.md"},{"id":"guide.workflow","kind":"guide","title":"Workflow and stage machine","summary":"Invoice/Payment split, actors, track A (merchant readiness), track B (buyer checkout), status machine, mismatch/memo/expiry scenarios.","auth":"none","when_to_use":"When you must decide what a state means or what happens next — this is the source of truth for stages.","keywords":["workflow","stages","status machine","expired","mismatch","memo","edge cases","spec"],"related":["concept.invoice_vs_payment","flow.accept_payment"],"source":"docs/workflow.md"}],"docs":[{"source":"docs/how-it-works.md","title":"How a crypto payment works, end to end"},{"source":"docs/quickstart-telegram-bot.md","title":"Quickstart: accept crypto in a Telegram bot"},{"source":"docs/ai-friendly.md","title":"AI-friendly by design"},{"source":"docs/merchant.md","title":"Merchant product guide"},{"source":"docs/workflow.md","title":"FreedomPayments workflow"},{"source":"docs/agent-access.md","title":"Agent access — make FreedomPayments discoverable and usable by other agents"},{"source":"README.md","title":"FreedomPayments"}],"discovery":{"llms_txt":"https://api.freedompayments.tech/llms.txt","llms_full_txt":"https://api.freedompayments.tech/llms-full.txt","catalog":"https://api.freedompayments.tech/v1/catalog","search":"https://api.freedompayments.tech/v1/search?q={query}","openapi":"https://api.freedompayments.tech/api/v1/openapi.json","ai_policy":"https://api.freedompayments.tech/ai-friendly","sitemap":"https://api.freedompayments.tech/sitemap.xml","manifest":"https://api.freedompayments.tech/.well-known/agent.json"}}