> ## 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. # Run Your Own x402 Facilitator > Step by step guide to self hosting an x402 facilitator: install the AlgoVoi payment rails, wire your domain, accept x402 payments in five minutes. Building agentic commerce and need an x402 facilitator on your own infrastructure? This guide takes you from zero to a running x402 endpoint under your own domain in five minutes. ## What you need * A Linux server (Ubuntu 24.04 recommended, any systemd distro works) * A domain or subdomain you control (`pay.yourco.com` in the examples) * An [AV-RAILS licence](https://api.algovoi.co.uk/suite-store) (one-time perpetual; the bundle arrives as a single encrypted `.algv`) No Docker, no cloud accounts, no package registry access required. The bundle self-installs and starts on SQLite. ## Step 1 — Extract the bundle When you purchase, you receive a signed licence key and a download link. Download the zip and extract it: ```bash theme={null} unzip algovoi-rails-bundle.zip # bundle.algv algovoi_unbundle.py INSTALL.txt enterprise-setup.sh run_all.sh GO-LIVE.md A2A-AGENT-CARD.md ``` Run the extractor with your licence: ```bash theme={null} python algovoi_unbundle.py --license-file licence.key --extract # Verifies the Falcon-1024 licence offline, decrypts, extracts 16 wheels + BUNDLE_MANIFEST.json ``` All 16 wheels are now in the current directory, integrity-checked against the manifest. ## Step 2 — Install and start One command installs all wheels into a virtualenv, writes hardened systemd units, and starts everything behind automatic HTTPS: ```bash theme={null} sudo ALGOVOI_DOMAIN=pay.yourco.com ALGOVOI_ACME_EMAIL=ops@yourco.com \ bash enterprise-setup.sh --license @licence.key ``` What this does: * Creates `/opt/algovoi/rails/venv` and installs all 16 wheels * Generates `/etc/algovoi/rails.env` with fresh secrets (HMAC, encryption keys, JWT secret) at `0600` * Writes and enables systemd units for the payment rails (port 443), operator panel (8443), and Substrate 2 control plane (9443) * Fetches a Let's Encrypt certificate for your domain and keeps it renewed automatically * Starts every service under `Restart=always` For an air-gapped install without a public domain, omit `ALGOVOI_ACME_EMAIL` and the installer uses a self-signed certificate instead. Verify everything is up: ```bash theme={null} systemctl status algovoi-rails algovoi-operator algovoi-substrate2 curl https://pay.yourco.com/health # {"status":"ok","chains":["base","algorand","solana","hedera","stellar","voi","tempo"]} ``` ## Step 3 — Wire your domain identity The gateway presents as **you**, not as us. One variable sets every public surface to your domain: ```bash theme={null} # Already set by enterprise-setup.sh if you passed ALGOVOI_DOMAIN GATEWAY_PUBLIC_URL=https://pay.yourco.com ``` With that set, your deployment exposes: * `https://pay.yourco.com/.well-known/did.json` — your `did:web:pay.yourco.com` document * `https://pay.yourco.com/.well-known/agent.json` — your A2A AgentCard (no AlgoVoi references) * `https://pay.yourco.com/x402/requirements` — your x402 endpoint * `https://pay.yourco.com/.well-known/security.txt` — your security contact No AlgoVoi identity, endpoints, or references appear anywhere on your deployment. ## Step 4 — Accept your first x402 payment Create a payment intent on the chain you want: ```bash theme={null} curl -X POST https://pay.yourco.com/v1/intents \ -H "Content-Type: application/json" \ -d '{ "network": "base", "asset": "usdc", "amount_minor": 100000, "order_ref": "order-001" }' # {"intent_id":"int_…","receive_address":"0x…","status":"pending"} ``` An x402 client sends `POST /v1/x402/requirements` to get the 402 challenge, pays on-chain, then sends `POST /v1/x402/verify` with the transaction. The gateway confirms the settlement, applies Base's finality rules, and returns a signed receipt: ```json theme={null} { "status": "settled", "receipt": { "alg": "falcon1024", "payload": { "network": "base", "asset": "usdc", "amount_minor": 100000, "…": "…" } } } ``` The receipt is a Falcon-1024 post-quantum-signed, no-PII proof. Anyone you hand it to can verify it offline with no service running. ## The four agentic protocols The same engine and the same receipt format handle all four protocols: | Protocol | What you implement | | -------- | ----------------------------------------------------------------------------------- | | **x402** | `GET /v1/x402/requirements` + `POST /v1/x402/verify` | | **MPP** | Same x402 surface; the `intent` extension handles recurring `charge`/`subscription` | | **AP2** | `POST /v1/ap2/mandate` renders a W3C Payment Request bound to your CartMandate | | **A2A** | `POST /v1/a2a/task` renders the intent as an Agent2Agent payment task | You do not need to implement protocol negotiation separately. The gateway handles the protocol surface; your application sees the same settled intent and signed receipt regardless of which protocol the payer used. ## Seven chains out of the box All seven chains ship in the bundle and register automatically on install. To enable the chains you settle on, add RPC endpoints to `/etc/algovoi/rails.env`: ```bash theme={null} BASE_RPC_URL=https://mainnet.base.org ALGORAND_INDEXER_URL=https://mainnet-idx.algonode.cloud SOLANA_RPC_URL=https://api.mainnet-beta.solana.com # HEDERA_MIRROR_URL, STELLAR_HORIZON_URL, VOI_INDEXER_URL, TEMPO_RPC_URL ``` Public defaults are pre-set for all seven chains. Use your own node or RPC provider for production. ## Upgrade to PostgreSQL when you scale The bundle starts on SQLite and exports to PostgreSQL by import when you need it. No schema migration required. ```bash theme={null} # Export from the running SQLite instance curl -X POST https://pay.yourco.com/admin/export-for-postgres > export.sql # Import into Postgres psql -d your_db < export.sql # Switch the connection string and restart systemctl restart algovoi-rails ``` ## What's in the bundle One licence, one `.algv`, one install command: * The payment rails engine across all seven chains * The post-quantum Substrate 2 core (Falcon-1024, JCS, receipt formats) * The full keystone estate (passport, federation validator, zero-knowledge receipts, delegation) * Substrate Guard Pro and Edge Sentinel (input-bounds, rate and replay protection) * The multi-tenant control plane and operator panel One-time perpetual licence. Runs on your own server. Buy it on the [AlgoVoi store](https://api.algovoi.co.uk/suite-store). For enterprise terms, [email us](mailto:hello@algovoi.co.uk).