Hackathon prototype · Celo mainnet · open source

Pay for an API with the money you already hold.

Payrail finds the service, checks what you hold, converts a supported local stablecoin into the payment currency only when it has to, pays through Celo’s x402 Buy gateway, and hands back the response with a receipt you can verify on-chain.

Explore the Repository Read the Getting Started Guide

No hosted demo yet: Payrail runs on your own machine. What that means.

Payrail API detail page: price in USDT, the seller's own price in cNGN, the response contract in plain words, and a Pay and Use API button
A published listing in the real app (local run): price, billing rule and the contract that decides whether you are charged.

What is it?

An API marketplace and payment agent. You pick a service; Payrail works out how to pay for it from the stablecoin you actually hold.

How does it work?

Price from the service’s own payment request, balance check, optional Textile FX conversion, x402 payment on Celo, then an on-chain check of what happened.

Why does it matter?

Many people and agents hold cNGN or another local stablecoin while the service wants USDT. Fixing that by hand, every time, is slow and risky. Payrail makes it one approved step.

How Payrail works

One payment, five steps

  1. 1

    Choose an API

    Browse the live Buy catalog (about 170 services) next to APIs listed by independent sellers.

  2. 2

    Use what you hold

    Pay with USDT directly, or pick a supported local stablecoin. You see the live rate, fee and the most you could spend first.

  3. 3

    Convert, if needed

    Only when the balance is the wrong currency and a route is live. Textile FX swaps it to USDT in one signed order.

  4. 4

    Pay on the rail

    The x402 payment goes to the Buy gateway on Celo. Spending limits, locks and a journal guard every step.

  5. 5

    Get response and receipt

    The response is saved and hashed. Settlement is re-checked on-chain. Anything uncertain stops and is never retried.

Which currencies, routes and services you can use depends on what is live and supported right now. The app shows the real status for each; nothing is offered that the server will not do.

What Payrail supports

What is verified, what is only tested, what is planned

Three honest groups. Nothing in the second or third group is claimed as a working feature.

Verified on mainnet

  • Direct x402 payments to the Buy gateway in USDT (3 real payments).
  • Convert-then-pay: cNGN to USDT through Textile FX, then the x402 payment (1 real order).
  • A Mento swap and a Textile swap, with the event attribution tag on every transaction Payrail submits.
  • ERC-8004 agent identity (agent 9906).
  • Receipts, saved response hashes and on-chain re-checks of every transaction.
  • Seller ownership proof with GitHub (OAuth, repository write access, proof file in the repo and on the host, endpoint check), run against real GitHub and a real host.

Implemented, tested with fakes

  • Seller flow: register, DNS or file proof, encrypted credentials, free test calls, response contracts, publish.
  • Outcome billing: buyers are charged only when a response satisfies the contract.
  • Browser-wallet purchase of a Buy API with in-app currency conversion.
  • Conversion from wARS, wBRL, IDRX and USDC: quoted live by Textile, never executed by Payrail.
  • Recovery tools (reconcile, resume, resolve an uncertain payment) and seller payout accounting.

Planned or not built

  • A hosted public deployment.
  • Seller payouts actually sent (no payout has ever been made).
  • On-chain escrow (a contract exists in the repo; it is not deployed or used).
  • Fiat on and off ramps, and providers beyond Buy.
  • Direct payment in USDC or USAT (accepted by Buy; Payrail only signs for USDT today).
  • An independent security review.
Network
Celo mainnet, chain 42220
Settlement currency
USDT
Conversion corridors (Textile, official Celo list)
cNGN (executed), wARS, wBRL, IDRX, USDC (quoted, not executed)
Payment rail
x402 via the Buy gateway; Mento router for some swaps
Receipts
JSON and CSV export from verified evidence

Proof

Real transactions you can check yourself

All on Celo mainnet. Each row links to the block explorer. The agent wallet signs; the payTo address belongs to the Buy gateway, which also submits the x402 settlement.

WhatAmountBlockTransaction
x402 payment to Buy, x.posts.search0.005 USDT799201940xfb012c51…17ac
x402 payment to Buy (direct order)0.005 USDT800017200x57c3c046…57fe
Textile FX swap, cNGN to USDT (convert-then-pay)1363.665 cNGN to 0.998910 USDT800387430x102eafff…acb7
x402 payment funded by that swap0.005 USDT800387640xf3652222…2c9c
ERC-8004 agent registration (agent 9906)n/a800326090xf654ea5f…ab1b

Agent wallet 0x652C9023626d1a00AD0d130C9cdc5C5f3644D2a4 (owner of ERC-8004 agent 9906, checked on-chain)

x402 payTo (Buy gateway) 0x20faAca5F980E29639A0FCC6dcA6988E18ed333B

Full evidence report Receipts (CSV) Receipts (JSON) Seller test API repo

Re-check it yourself with node scripts/evidence.ts --verify: it re-reads every transaction from several Celo RPC endpoints and recomputes the response hashes.

For sellers

More than a catalog of someone else’s APIs

A seller signs in with a wallet, lists an API, proves they own it, tests it for free, defines what a qualifying response looks like, and publishes. Buyers pay only when the response meets that contract. Credentials are encrypted and sent only to the verified host.

Marketplace designGitHub verification setup

Payrail Explore APIs page: one independent seller listing next to Buy gateway services, each with a price in USDT
Explore: an independent seller listing beside Buy services.

Getting started

Run it on your machine

Needs Node.js 22.18 or newer. Nothing to build, and the commands below never spend money.

  1. Install and check

    git clone https://github.com/justriri/Payrail.git
cd Payrail
npm install
cp .env.example .env      # Windows PowerShell: Copy-Item .env.example .env
npm run check             # type check and all tests (fakes only, about 5 minutes)

  2. Open the app (read-only)

    npm run serve
# then open http://127.0.0.1:4402

    Live catalog, balances and quotes. No key is loaded, so it cannot pay.

  3. Plan an order without spending

    node --env-file=.env scripts/order.ts --service x.posts.search
node --env-file=.env scripts/routes.ts
node --env-file=.env scripts/evidence.ts --verify

    Prints the route, cost and a plan digest. Paying needs a wallet key file kept outside the project, an explicit --execute flag and your confirmation.

  4. Go further

    Demo walkthroughArchitectureWhat is real, what is notLive test runbookWallet key handling

Build on it

Limits

Honest status

  • Prototype. Built for the Celo Agents on Open Rails hackathon. It is not production-ready and has had no third-party security review.
  • Local only. There is no hosted app, so there is no live demo link. This page is static and shows the real app through screenshots and on-chain evidence.
  • Mostly one real route. Only cNGN to USDT has been executed on mainnet. The other corridors are quoted live, not executed.
  • Custody. In marketplace mode, buyer deposits sit at an operator-controlled address and a ledger, and seller payouts are operator-run and have not been used.