> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Rails (SQLite-first)

> A self-hosted, multi-chain payment gateway you run on your own infrastructure. Create a payment intent, watch the chain for the matching settlement with that chain's finality applied, and emit a post-quantum-signed, no-PII settlement receipt that folds into your evidence estate. All seven chains ship in one bundle; one engine, one port.

## What it is

The **Payment Gateway** is a self-hosted service that takes a stablecoin (or native-asset)
payment from intent to signed, audit-ready proof. You run it on your own infrastructure: it
holds no account with us, makes no outbound call to us, and never phones home.

It does three things end to end:

1. **Creates a payment intent** for a specific network, asset, amount, recipient, and your own
   order reference, and hands back the receive address to show your customer.
2. **Watches that chain** for the matching settlement, applying the **finality rules of that
   specific network**, and resolves the intent to a clear status.
3. **Emits a signed settlement receipt** that is no-PII, offline-verifiable, and folds straight
   into the [Compliance Command Center](/compliance-command-center) evidence chain.

It is built on the same **Substrate 2** crypto core as the rest of the suite, so a settled
payment becomes evidence that is unforgeable today and stays unforgeable after the migration to
post-quantum cryptography.

<CardGroup cols={2}>
  <Card title="One engine, every chain" icon="link">
    A single gateway engine and a single service port. Every chain ships in the one bundle and is
    discovered automatically when the engine starts; enable the networks you settle on and leave
    the rest idle.
  </Card>

  <Card title="Settlement and finality" icon="circle-check">
    Confirms a payment is included, succeeded, reached the right recipient, for the right amount,
    in the right asset, with each network's distinct finality model applied, not a one-size "is
    it mined".
  </Card>

  <Card title="Signed, no-PII evidence" icon="shield-halved">
    Every resolved settlement becomes a post-quantum-signed receipt that carries amounts, refs,
    and hashes but never personal data, and verifies offline with no service running.
  </Card>

  <Card title="Self-hosted, no lock-in" icon="server">
    Runs as one process on your infrastructure. Bring your own chain RPC endpoints. Nothing
    leaves your network, and the receipts verify long after the service is switched off.
  </Card>
</CardGroup>

## How it differs from Settlement Verification

[Settlement Verification](/settlement-verify) is a read-only OEM **SDK** you embed inside your
own product to answer "did this settle and finalise". The Payment Gateway is a **service you
run**: it owns the whole intent lifecycle (create, watch, resolve, attest), produces the signed
evidence chain, and is the surface a full-custody payout phase plugs into. If you only need to
confirm an arbitrary settlement inside your own backend, the SDK is the lighter fit. If you want
a gateway that runs the payment from request to proof, this is it.

## The intent lifecycle

You describe the payment you expect; the gateway resolves what actually happened on-chain to one
of a small, closed set of outcomes:

| Status       | Meaning                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `pending`    | Intent created, no qualifying transfer to the recipient seen yet                                                  |
| `confirming` | A matching transfer is on-chain but has not reached the chain's finality threshold                                |
| `settled`    | A transfer for the expected amount (or more) reached the expected recipient, in the expected asset, and finalised |
| `underpaid`  | A transfer to the recipient landed for less than the intent amount                                                |

Matching is by exact recipient, asset, and amount, so a transfer to a different address simply
never qualifies (the intent stays `pending`) rather than being mistaken for payment. When a
qualifying transfer finalises, the gateway records a settlement entry and signs it. There is no
ambiguous "probably paid": the outcome is explicit, and the proof of how it was reached travels
with the receipt.

## The settlement receipt

Each resolved settlement is written to an append-only, hash-chained ledger and signed with
Falcon-1024 (NIST Level 5) through Substrate 2. A receipt is:

* **No-PII by construction.** It carries the network, asset, amounts (as exact integer minor
  units, never lossy floats), confirmations, finality, your order reference, and content-address
  hashes. It never carries names, emails, or any personal data. The payer and recipient appear
  only as hashed references, not raw addresses.
* **Offline-verifiable.** Anyone you hand the exported pack to can verify every signature and the
  full chain with no service running and no network access. A single altered byte breaks
  verification.
* **CCC-ingestable.** The receipts export as a pack that drops straight into the Compliance
  Command Center, where they appear in the consolidated posture as **"Payment Gateway ·
  settlement receipts"** alongside the rest of your evidence estate. Settlement evidence sits next
  to your sanctions, retention, and audit evidence in one auditor pack.

## Seven chains, one bundle

All seven chains ship in the one bundle and each registers itself with the engine on install.
Coverage is deep where generic multi-chain tooling is thin: the long-tail asset and finality
semantics are handled correctly per network.

| Chain        | Network kind    | Asset detected | Settlement model                                                                  |
| ------------ | --------------- | -------------- | --------------------------------------------------------------------------------- |
| **Base**     | EVM L2          | USDC (ERC-20)  | Token-transfer log detection to the recipient, with a confirmations finality rule |
| **Tempo**    | EVM L1          | USDCe (TIP-20) | EVM token-transfer detection, same proven path as Base, parameterised for Tempo   |
| **Solana**   | Solana          | USDC (SPL)     | Signature scan plus token-balance-delta confirmation at the chosen commitment     |
| **Algorand** | Algorand        | USDC (ASA)     | Asset-transfer detection via the indexer, with Algorand instant finality          |
| **VOI**      | Algorand-family | Native VOI     | Native-payment detection via the AVM indexer                                      |
| **Hedera**   | Hedera          | USDC (HTS)     | Token-transfer detection via the Mirror Node, native Hedera finality              |
| **Stellar**  | Stellar         | USDC           | Payment detection via Horizon, exact 7-decimal asset amounts                      |

Each chain takes its RPC or indexer endpoint from configuration (bring your own node, with
sensible public defaults), applies that network's confirmation and finality rules, and feeds the
same engine and the same receipt format. Every network is present out of the box, so there is no
per-chain integration to add.

<Note>
  Five of the seven chains have been validated **end to end on live networks** (Base, Algorand,
  VOI, Hedera, Stellar): a real on-chain settlement detected and turned into a signed receipt that
  verifies in the Command Center. Solana and Tempo are validated against their settlement logic and
  go live with a keyed RPC endpoint for those networks.
</Note>

## One engine, one port

All seven chains run in one engine as **one process on one port (8090)**. You do not get a service
per chain. A request names its `network`, and the engine routes it to the matching handler. Every
network lives in the same service; there are no extra ports, processes, or moving parts to operate.
See the [ports and interfaces reference](/substrate-2-ports) for where it sits in the suite.

The service exposes a small, stable HTTP surface: create an intent, check an intent, list the
installed chains, report health, and export the signed settlement pack for the Command Center.
There is no SDK to adopt and no shared library to pin; any backend in any language talks to it
over plain HTTP.

## Agentic payment protocols

The gateway speaks the agentic payment protocols on top of the same verify-then-prove engine, so a
payment negotiated by an agent settles and is receipted the same way a direct payment is:

* **x402.** `POST /v1/x402/requirements` returns a spec-v1 `402 Payment Required` body for an intent;
  `POST /v1/x402/verify` confirms settlement and returns the signed receipt as proof. The proof is the
  Falcon-1024 receipt itself, verifiable offline against the gateway key, with no shared secret.
* **MPP.** The x402 `intent` extension (`charge` or recurring `subscription`).
* **AP2.** Renders a merchant CartMandate's price as a W3C Payment Request and binds the `cart_id` into
  the signed receipt, so the settlement proof commits to the cart it paid.
* **A2A.** Renders the intent as an Agent2Agent payment task and binds the `task_id` into the receipt.

In every case the gateway is the settlement-proof layer beneath the protocol: it verifies the on-chain
settlement and signs the evidence. Mandate bounds, consent, and agent negotiation stay in the protocol
layer.

## Custody and payout

The gateway does both halves of a payment: it detects and proves inbound settlement, and it signs
and broadcasts outbound payouts. Custody is **operator-held**: the signing key for each chain lives
on your own infrastructure, supplied by environment and never by AlgoVoi, and a payout is fail-closed
if no key is configured. `POST /v1/payouts` signs and broadcasts on the chain you name and returns a
signed, no-PII `gateway_payout` receipt that folds into the Command Center next to your settlement
evidence. Operator-held custody is available across all seven chains; an HSM or KMS-backed signer
(the key never leaving the HSM) is the same interface, offered as a per-deployment option.

Optionally, a payout can be **bound to an authorizing decision**: configure the gateway to sign a payout
only against a fresh, valid ALLOW from the [Spend Guardrail](/spend-guardrail) for that exact amount and
destination. The authorizing decision is recorded in the payout receipt, so the evidence chain shows
authorized then settled as one provable sequence, and a payout with no valid authorization is refused.

## Cryptography

* **Detection reads each chain's native signatures** (Ed25519, secp256k1, and so on): classical
  cryptography inherent to the chains, not something the gateway supplies or replaces.
* **The receipts it produces are post-quantum signed** with Falcon-1024 through Substrate 2, and
  canonicalised with JCS (RFC 8785) so the signed bytes are identical on every implementation. A
  settled payment becomes evidence that survives the post-quantum migration.

## Who it's for

* **Merchants and platforms** that want to accept stablecoins across several chains on their own
  infrastructure and keep an audit-grade record of every settlement.
* **PSPs and marketplaces** reconciling inbound settlements across heterogeneous networks who need
  one engine and one evidence format rather than one integration per chain.
* **Regulated and agentic systems** that must prove, offline and after the fact, that a payment
  finalised on-chain, to whom, and for how much, without exposing any personal data in the proof.

## What's in the bundle

One licence installs the whole stack as a single encrypted, offline-verifiable `.algv`:

* **The payment rails engine** across all seven chains: intent lifecycle, settlement and finality
  detection, operator-held payouts, and the x402, MPP, AP2 and A2A protocols on one port.
* **The post-quantum Substrate 2 core**: Falcon-1024 signing, JCS canonicalisation, and the
  receipt formats every settlement is signed with.
* **The full keystone estate**: the passport-to-journey lifecycle, the federation validator, the
  zero-knowledge receipt service, and delegation refs.
* **A hardened security layer**: Substrate Guard Pro (input-bounds and UTF-8 admission with signed
  decisions) and Edge Sentinel (runtime IP, rate and replay protection).
* **Evidence and retention**: Command Center ingest and the hash-linked retention chain, so every
  settlement folds into one offline-verifiable posture.

The multi-tenant control plane, operator panel, and per-tenant isolation run it all. It starts on
SQLite for a five minute install and upgrades to PostgreSQL by import when you scale.

## Get the bundle

The rails ship as **one self-hosted bundle**: the gateway engine (intent lifecycle, signed
settlement evidence, the service, and the plugin framework), all seven chains, the full keystone
estate, the hardened security layer, and the post-quantum Substrate 2 core, on a one-time perpetual
licence. It is self-hosted and is not distributed on public package registries. It is also
**included in the [Substrate 2 on-prem suite](/substrate-2)**.

<Card title="Buy the Payment Rails bundle" icon="cart-shopping" href="https://api.algovoi.co.uk/suite-store">
  One licence installs the whole stack with every chain. Buy it on the [AlgoVoi
  store](https://api.algovoi.co.uk/suite-store), or take it in the [Substrate 2 on-prem
  suite](/substrate-2). For enterprise terms, [email us](mailto:hello@algovoi.co.uk).
</Card>