AGENTRAIL

Contract Address for $AGENTRAIL:

55VUfgxibnUCYY9eY3jGoiHWB6Uuat3uddLVtVpjXi5A

A policy engine that sits between an AI agent's payment intent and the signature that sends it on Solana — evaluating every request against limits its human owner set, before any money moves.

This is a library, not a service. You install it, run it in your own process, hold your own keys, and fund your own wallets. Nothing here ever touches your money on our behalf. (A hosted version is planned — see Status — but it doesn't exist yet, and won't hold real funds until custody moves off the local keystore described below.)

What it actually does

Every payment goes through the same path, whether it's called directly or via the demo agent's x402 pay-per-call flow:

1. An agent submits a payment intent (token, amount, payee, an idempotency key).
2. The policy engine evaluates it — kill switch, token/payee allowlists, per-transaction and rolling-window and lifetime caps, rate limits, time windows, escalation thresholds — and either allows it, denies it with a specific reason, or routes it to a human for approval.
3. An allowed intent is reserved (budget held) before anything is signed.
4. The signer signs — or refuses, if the kill switch was thrown in the meantime — and the transaction is submitted to Solana.
5. The reservation resolves to settled (confirmed on-chain) or released (failed, expired, or denied), never left ambiguous.

docs/operations.md documents the on-call-facing edges of this — the idempotency-key state machine, why the kill switch can't recall a transaction already on the wire, and the runbook for a stuck reservation — worth reading before you build anything that retries payments.

Install

Not on the npm registry yet — see Status. Once published:

npm install @pyco404/agentrail

import { evaluate, evaluateAndReserve, InMemoryReservationStore } from '@pyco404/agentrail';

@pyco404/agentrail ships the core types, the pure policy engine, the reservation/idempotency layer, the chain submission path, and LocalKeyProvider (an encrypted-at-rest local keystore). It does not pull in pg/drizzle-orm — the Postgres-backed store is opt-in, for anyone who wants durable reservations across process restarts; InMemoryReservationStore is enough to get started.

See it pay for something, in 2 minutes

The fastest way to understand the whole path is to watch it happen. src/agent/ is a small demo agent that pays a local x402-gated endpoint per call, on Solana devnet, with a real (worthless, devnet-only) SPL token — real policy checks, real signing, real on-chain settlement, not a simulation.

git clone https://github.com/pyco404/agent-rail
cd agent-rail
npm install

export WALLET_KEYSTORE_PASSPHRASE=$(openssl rand -base64 32)
npm run demo:setup   # provisions a demo mint + two devnet wallets, funds them
npm run demo          # runs the pay-per-call loop

It pays a few times, then hits a real policy denial once its lifetime cap is spent. Press k while it's running to engage the kill switch live and watch the next call get refused before it ever reaches the signer.

A minimal example

import { evaluate } from '@pyco404/agentrail';

const verdict = evaluate(policy, intent, history, new Date());
// { type: 'allow' }
// { type: 'requiresApproval' }
// { type: 'deny', reason: { code: 'per_transaction_cap_exceeded', token, cap } }

evaluate() is pure — a policy, an intent, spend history, and a clock in, exactly one decision out, no I/O. Reserving budget against a wallet's real, persisted history goes through evaluateAndReserve() instead, which wraps the same evaluation in the wallet's transaction lock.

Status

What's actually built, not aspirational — kept honest at agent-rail.xyz/status. Short version: the policy engine, chain submission path, and local signer are built and tested; this npm package (@pyco404/agentrail) is in progress — not yet published to the registry; a hosted HTTP service is planned but not started.

License

MIT — see LICENSE.