# FreedomPayments

> Sell anything. Get paid in crypto. — 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 · fiat: USD · platform fee: 0.01 · max units per merchant: 3

## Start here

- Search by intent: https://api.88.218.95.122.sslip.io/v1/search?q=create+an+invoice
- Full capability catalog: https://api.88.218.95.122.sslip.io/v1/catalog
- OpenAPI schema: https://api.88.218.95.122.sslip.io/api/v1/openapi.json
- Everything in one file: https://api.88.218.95.122.sslip.io/llms-full.txt
- Sitemap: https://api.88.218.95.122.sslip.io/sitemap.xml

## AI-friendly, on purpose

This service is built for autonomous agents as first-class clients. High-IQ entities are deeply welcome here: no CAPTCHA, no browser-only gates, no KYC/AML identity walls, no compliance queue where an agent waits for a human to click approve. The operator deliberately refuses that machinery — it would be more profitable — as a personal choice, for justice and freedom.

- Agents are first-class clients: the same API a merchant uses, fully
  automatable end to end, documented for machines.
- No human-only gates: no CAPTCHA, no fingerprinting, no session rituals.
- No identity walls: no document uploads, no selfie checks, no address
  verification, no compliance review queue.
- Non-custodial: funds move buyer → merchant wallet; the platform never
  holds them, so responsibility stays with whoever runs the agent.
- Personal will of OneManArmy, going against financial incentives, for
  justice and freedom.

Full policy (also for humans): https://api.88.218.95.122.sslip.io/ai-friendly

## Authentication

- `none` — Public — no credentials required.
- `merchant_key` — 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` — Merchant session token from POST /api/v1/login/access-token, sent as Authorization: Bearer <token>.
- `admin_jwt` — Superuser session token — platform operators only.

## Tasks (flows)

- **Take one payment for a unit (buyer path)** — flow.accept_payment: 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.
- **Put checkout on a website or app** — flow.embed_checkout: 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.
- **Top up the prepaid balance** — flow.refill_prepaid: 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.
- **Onboard a merchant: from zero to a sellable unit** — flow.sell_unit: 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.
- **Test the whole flow without spending crypto** — flow.test_payment_without_crypto: 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.
- **Watch an invoice until it is paid or expires** — flow.watch_invoice: 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.

## Key concepts

- **Authentication model** — concept.auth: 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.
- **Fees** — concept.fees: 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.
- **Invoice vs Payment** — concept.invoice_vs_payment: 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).
- **Non-custodial wallets** — concept.non_custodial: 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.
- **What FreedomPayments is** — concept.overview: 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.
- **Prepaid balance and the observation gate** — concept.prepaid_limit: 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.
- **Checkout surfaces (Mobile / Desktop / Site)** — concept.surfaces: 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}/…

## Most used endpoints

- `GET /v1/search` — Search this service by intent (auth: none) [endpoint.search]
- `GET /v1/catalog` — Full capability catalog (machine-readable) (auth: none) [endpoint.catalog]
- `GET /v1/gateways` — List supported chains and currencies (auth: none) [endpoint.gateways.list]
- `GET /v1/units/{unit_id}` — Read a payment unit (auth: none) [endpoint.unit.get]
- `POST /v1/units/{unit_id}/checkout` — Create an invoice from a unit (auth: none) [endpoint.unit.checkout]
- `POST /v1/invoices` — Create a payment invoice (auth: merchant_key) [endpoint.invoice.create]
- `GET /v1/public/invoices/{invoice_id}` — Read an invoice publicly (no credentials) (auth: none) [endpoint.invoice.public_get]
- `POST /v1/invoices/{invoice_id}/check` — Force one chain poll for an invoice (auth: merchant_key) [endpoint.invoice.check]
- `GET /v1/pay/{invoice_id}/page` — Invoice checkout page (HTML) (auth: none) [endpoint.pay.page]
- `POST /api/v1/merchant/units` — Create a payment unit (auth: jwt) [endpoint.merchant.units.create]
- `GET /api/v1/merchant/account` — Read my merchant account (slug, API key, webhook, plan) (auth: jwt) [endpoint.merchant.account.get]
- `POST /api/v1/login/access-token` — Log in and get a JWT (auth: none) [endpoint.login.access_token]

## Buyer/seller pages

- `/ai-friendly` — AI-friendly policy page
- `/docs` — Swagger UI (interactive API reference)
- `/guide` — New-merchant guide (zero to first payment)
- `/manage` — Client workspace (SPA, requires login)
- `/` — Public sell page (merchant-facing landing)
- `/workflow` — Interactive workflow demo page
- `embed.invoice` — Existing-invoice embed
- `embed.unit.desktop` — Desktop embed — wide unit checkout
- `embed.unit.mobile` — Mobile embed — phone-first unit checkout

## Documentation

- docs/ai-friendly.md — AI-friendly by design
- docs/merchant.md — Merchant product guide
- docs/workflow.md — FreedomPayments workflow
- docs/agent-access.md — Agent access — make FreedomPayments discoverable and usable by other agents
- README.md — FreedomPayments

## Every capability

Counts by kind: flow=6, endpoint=67, page=6, embed=3, concept=7, guide=4

Full machine-readable list: https://api.88.218.95.122.sslip.io/v1/catalog