Run Your Own x402 Facilitator

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 (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:

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:

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:

sudo ALGOVOI_DOMAIN=pay.yourco.com [email protected] \
     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:

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:

# 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:

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:

{
  "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:

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.

# 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

Get the bundle

One-time perpetual licence. Runs on your own server. Buy it on the AlgoVoi store. For enterprise terms, email us.

Get started

Platform

Concepts

Keystone

Agent Mesh

Substrate 2

Commercial

Open substrate

Payment protocols

Chains

Integrations

Help

Company

Run Your Own x402 Facilitator

What you need

Step 1 — Extract the bundle

Step 2 — Install and start

Step 3 — Wire your domain identity

Step 4 — Accept your first x402 payment

The four agentic protocols

Seven chains out of the box

Upgrade to PostgreSQL when you scale

What’s in the bundle

Get the bundle

​What you need

​Step 1 — Extract the bundle

​Step 2 — Install and start

​Step 3 — Wire your domain identity

​Step 4 — Accept your first x402 payment

​The four agentic protocols

​Seven chains out of the box

​Upgrade to PostgreSQL when you scale

​What’s in the bundle

Get the bundle

What you need

Step 1 — Extract the bundle

Step 2 — Install and start

Step 3 — Wire your domain identity

Step 4 — Accept your first x402 payment

The four agentic protocols

Seven chains out of the box

Upgrade to PostgreSQL when you scale

What’s in the bundle