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 → poll pattern 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                            # merchant session (payee-gated ops)

# Authorize 10 USDC into escrow, then capture it (poll between on-chain steps)
PID=$(rail0 payments create -F <payer> -T <payee> -t USDC -a 10.00 -c 5042002 \
        -p @payer --json | jq -r .id)
rail0 payments authorize "$PID" -p @payee
rail0 payments capture   "$PID" -a 10.00 -p @payee

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
refund	payee	return captured funds to the buyer (partial or full)
dispute / close	payer	buyer signal — no funds move

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 on your PATH
• jq (to read the CLI's --json output)
• 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)

The status poller is inlined in SKILL.md (the wait_for function), 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.