rail0-skill

Make and manage stablecoin (USDC) payments over the rail0 gateway from an AI agent — the full authorize → capture lifecycle plus charge, void, release, refund, and dispute — driven by the rail0 CLI.

A Claude Agent Skill. Point your agent at a rail0 gateway and it can take, capture, refund, or cancel stablecoin payments correctly: the skill encodes the lifecycle rules, who signs what, and the asynchronous act → wait pattern (-w) so operations never race the chain.

Install

npx skills add commercelayer/rail0-skill

Then just ask your agent to make or manage a rail0 payment.

Quickstart — what the agent runs

export RAIL0_BASE_URL=https://your-gateway
rail0 auth login -p @payee          # a session for reads; signing commands sign in themselves

# Authorize 10 USDC into escrow, then capture it. -w waits for each on-chain step;
# --yes is required for fund-moving commands in a non-interactive shell.
PID=$(rail0 payments create -F <payer> -T <payee> -t USDC -a 10.00 -c 5042002 \
        -p @payer -q)
rail0 payments authorize "$PID" -p @payee -w
rail0 payments capture   "$PID" -a 10.00 -p @payee --yes -w

Lifecycle at a glance

Operation	Who signs	What it does
authorize → capture	payer opens, payee captures	hold funds in escrow, capture later (partial or full)
charge	payee	one-shot: pay through immediately, no escrow
void	payee	cancel an untouched authorization (before any capture)
release	payer or payee	return the uncaptured escrow after authorizationExpiry (closes as refunded when it settles everything)
refund	payee	return captured funds to the buyer (partial or full)
dispute / close	payer	buyer signal — no funds move; optional reason code from rail0 disputes reasons

See references/lifecycle.md for the state machine, guards, and the two on-chain balances that drive the next legal step.

Requirements

• The rail0 CLI ≥ v1.3.0 on your PATH (dispute-reason codes, payments update)
• jq (optional — to read fields from the CLI's --json output; -q prints just the id)
• A reachable rail0 gateway — set RAIL0_BASE_URL

What's inside

• SKILL.md — the skill: mental model, setup, per-operation recipes, error handling, safety
• references/ — lifecycle/state-machine + the full command reference
• evals/ — the test prompts used to validate the skill (4/4 passing end-to-end on Arc testnet)

Waiting for the chain is built into the CLI (-w on every lifecycle command, and rail0 payments wait), so the skill needs nothing bundled to run.

Security

Private keys stay local. The CLI signs locally and sends only signatures and signed transactions to the gateway — never the key. Prefer the OS keychain (rail0 keys add → @name) or a secrets-manager-injected RAIL0_PRIVATE_KEY; never paste a raw key inline. See the skill's "Signing keys — reference them, never embed them" section, and SECURITY.md for the full trust model.

License

MIT © Commerce Layer — see LICENSE.