> ## 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: Setup and Deployment

> Install and go live with the AlgoVoi Payment Rails bundle: one command brings the stack up under systemd behind TLS, white labelled to your own domain.

AlgoVoi Payment Rails is a single encrypted, offline-verifiable bundle that turns a
stablecoin payment intent into a signed, audit-ready proof across seven chains. It runs
x402, MPP, AP2 and A2A on your own infrastructure: it holds no account with us, makes no
outbound call to us, and never phones home. Your Falcon-1024-signed bundle licence is both
the decryption key and the runtime licence, so one file extracts the bundle and unlocks
every service.

The install is designed to be short. One command brings the whole stack up, and one value
brands every public surface to you. This guide walks the full path from a fresh machine to
a live, white-labelled deployment.

***

## 1. What is in the bundle

Everything ships in one licence-gated `.algv` file. There is nothing else to download.

| Group    | Components                                                                                                                          |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Rails    | payment gateway (x402, MPP, AP2, A2A), operator control plane, on-chain settlement verifier                                         |
| Keystone | bound lifecycle passport, federation validator, zero-knowledge receipt service, delegation refs                                     |
| Core     | post-quantum Substrate-2 (Falcon-1024, ML-DSA-65, JCS canonicalisation, policy binding) and its control panel                       |
| Security | Substrate Guard Pro (input-bounds and UTF-8 admission, signed decisions) and Edge Sentinel (runtime IP, rate and replay protection) |
| Console  | the operator control panel: one login over TLS for merchants, payments, refunds, keys, per-network config, compliance and audit     |

SQLite-first: you are live in five minutes on a single file, and you upgrade to PostgreSQL
by import when you want more write concurrency.

***

## 2. Install in one command

Prerequisites: a Linux host with Python 3.11+, run as root. Save your bundle licence as
`licence.key` in the same directory as `bundle.algv`, `algovoi_unbundle.py` and
`enterprise-setup.sh`.

```bash theme={null}
sudo ALGOVOI_DOMAIN=pay.yourco.com ALGOVOI_ACME_EMAIL=ops@yourco.com \
     bash enterprise-setup.sh --license @licence.key
```

That one command verifies your licence offline, extracts the wheels with per-file SHA-256
checks, installs the rails and the commercial layer into a dedicated virtualenv, generates
and persists every production secret, initialises the database in WAL mode, installs each
service as a hardened `systemd` unit with automatic restart, and fronts the whole stack with
Caddy over HTTPS. When it finishes it prints the live URLs and your credentials.

* With a real, reachable domain it obtains a Let's Encrypt certificate automatically.
* With no domain (or an internal name) it generates a self-signed certificate and makes no
  outbound call, so the same command works air-gapped.

### Manual install (without systemd)

If you would rather run the stack yourself, extract and install the wheels, then start
everything with the bundled launcher:

```bash theme={null}
python -m pip install cryptography pqcrypto rfc8785
python algovoi_unbundle.py --license @licence.key --out ./algovoi bundle.algv
pip install ./algovoi/algovou_control_plane-*.whl    # rails + dependencies
pip install --no-deps ./algovoi/*.whl                # Keystone / Substrate-2 layer
bash run_all.sh                                       # starts every service
```

`run_all.sh` generates and persists the same secrets to `.rails.env` on first run, so a
restart reuses them and your sessions and encrypted data survive.

***

## 3. Your identity, one knob

The deployment is white-label. You set your domain once, and the entire public surface
reconfigures itself to you, with no per-endpoint configuration. `ALGOVOI_DOMAIN` sets
`GATEWAY_PUBLIC_URL=https://pay.yourco.com`, and from that single value everything derives:

| Surface (served on your domain)      | Becomes                                  |
| ------------------------------------ | ---------------------------------------- |
| `/.well-known/agent.json` (A2A card) | your URL, generic name, your JWKS        |
| `/.well-known/did.json`              | `did:web:pay.yourco.com`, your endpoints |
| `/.well-known/security.txt`          | `security@pay.yourco.com`, your host     |
| `/compliance/attestation`            | your operator identity, your DID         |
| `/discovery/resources`, `/mpp/*`     | your facilitator and probe URLs          |

No AlgoVoi identity, endpoints or references appear anywhere on your deployment. That is the
whole configuration. You are live.

Your A2A agent card and compliance receipts are cryptographically signed by default: the
enterprise installer generates an Ed25519 key (`VERASCORE_SIGNING_KEY_PEM_B64`) that never
leaves your host, and the card self-signs (A2A section 8.4) against your own
`/.well-known/jwks.json`, never ours. To use a key you already control, set
`VERASCORE_SIGNING_KEY_PEM_B64` before install and the installer keeps it.

The A2A surface is **dual-compatible**: one endpoint serves both A2A v0.3 and v1.0.1 clients.
A client selects with the `A2A-Version` header (absent is treated as 0.3); the agent card
advertises `supportedInterfaces` for HTTP+JSON and JSON-RPC at both versions, so clients
self-select. Both a REST binding (`/message:send`, `/tasks/*`) and a JSON-RPC 2.0 endpoint
(`/a2a/jsonrpc`) are exposed, each serving both versions.

***

## 4. Ports and consoles

The installer puts the payment rails on 443 and moves the admin surfaces up, so the consoles
never contend with live transactions.

| Port     | Surface                                                                      | Who uses it                     |
| -------- | ---------------------------------------------------------------------------- | ------------------------------- |
| **443**  | Customer payment rails (signup, x402, MPP, AP2, A2A)                         | payers, agents, facilitators    |
| **8443** | Operator control plane (tenant, network and RPC API)                         | your integration and automation |
| **9443** | Operator control panel (2FA console: services, chains, compliance, keystone) | your operators                  |

The rails must own 443: external agents, payers and facilitators resolve you at
`https://pay.yourco.com` with no port. If something else already listens on 443 on that
host, move it, not the rails. The internal services bind to loopback only and are never
exposed. Ports follow [Ports and interfaces](/substrate-2-ports).

***

## 5. First sign-in and going live

When the installer finishes it prints the live URLs and your first credentials, which are
also stored in `/etc/algovoi/rails.env` (root-readable):

* `ADMIN_API_KEY` authenticates automation against the operator control plane on 8443.
* `PANEL_TOKEN` is the login for the operator control panel on 9443.
* The Substrate-2 panel admin token is written to the data directory (or read it from
  `journalctl -u algovoi-substrate2-controlplane`).

Sign in to the control panel at `https://pay.yourco.com:9443/`. It is the single operator
console: from one login you manage merchants, payments, refunds, invoices, API keys,
per-network configuration, store integrations, compliance posture and a tamper-evident audit
log. Enrol authenticator-app 2FA on first sign-in. The full page-by-page walkthrough is in
the [Operator Control Panel](/operator-control-panel) guide.

**Point each chain at an RPC endpoint.** The one step that makes settlement live is giving
each chain you settle on an RPC endpoint, from the control panel's per-network configuration.
Until a chain has an endpoint it is configured but idle.

**Review the compliance posture.** `/compliance/attestation` ships a UK regulatory posture
(MLR 2017, SAMLA 2018 and similar) as a template. It is transparency metadata and does not
affect payment processing. If you operate in another jurisdiction, review that posture for
your own situation before relying on it publicly.

***

## 6. Optional configuration

You do not need any of these to be live. Set them in `/etc/algovoi/rails.env` and run
`sudo systemctl restart algovoi-gateway` only to override the sensible defaults.

| Variable                        | Default                | Sets                                      |
| ------------------------------- | ---------------------- | ----------------------------------------- |
| `AGENT_CARD_NAME`               | `Payment Agent`        | A2A card display name                     |
| `AGENT_CARD_ORG`                | (none)                 | organisation block on the card            |
| `OPERATOR_NAME`                 | your host              | operator name in compliance and discovery |
| `OPERATOR_CONTACT`              | (none)                 | operator contact in the attestation       |
| `SECURITY_CONTACT`              | `security@<your-host>` | security.txt contact                      |
| `VERASCORE_SIGNING_KEY_PEM_B64` | (unset, card unsigned) | your Ed25519 key: the card self-signs     |

***

## 7. Verification checklist

Run these after install to confirm the deployment is healthy.

| Check                                                     | Expected                                        |
| --------------------------------------------------------- | ----------------------------------------------- |
| `systemctl is-active algovoi-gateway` and the other units | `active`                                        |
| `GET https://pay.yourco.com/health`                       | 200                                             |
| `GET https://pay.yourco.com/.well-known/agent.json`       | your domain and identity, no AlgoVoi references |
| `GET https://pay.yourco.com/.well-known/did.json`         | `did:web:pay.yourco.com`                        |
| Sign in to the control panel on 9443 with `PANEL_TOKEN`   | console loads, every tab clickable              |
| Enrol 2FA                                                 | QR and setup key shown, code accepted           |
| Configure an RPC endpoint for one chain                   | chain moves from idle to live                   |
| Create a payment intent and settle it on that chain       | signed, audit-ready receipt                     |

This is the same sequence that a clean install is validated against before each release.

***

## 8. Security model

* **Self-hosted and air-gap capable**: verifies and decrypts with no network, and runs with
  no phone-home.
* **Own custody**: you hold the keys and take payout to your own addresses; the rails never
  hold your funds on our behalf.
* **Post-quantum evidence**: receipts are anchored with Falcon-1024 and ML-DSA-65 over a JCS
  canonicalisation core, so proofs stay verifiable for the long term.
* **Hardened by default**: Substrate Guard Pro and Edge Sentinel ship in the bundle, every
  service runs as a locked-down `systemd` unit, and the admin consoles are kept off the
  public rails port.
* **White-label**: nothing on your deployment advertises AlgoVoi.

Next, keep the [Operator Control Panel](/operator-control-panel) guide open as your
day-to-day reference, and see the [Payment Rails](/payment-rails-sqlite) product page for
what the rails do end to end.