@voidly/pay-cli

@voidly/pay-cli

Command-line interface for Voidly Pay — shell, CI and scripting access to every primitive on the rail. Ships two binaries:

• voidly-pay — the full CLI (Node).
• pay-curl — a zero-dependency bash x402 client. curl, but it pays HTTP 402 challenges automatically. No Node, no Python: bash + curl + jq + openssl.

Install

npm install -g @voidly/pay-cli
# or one-shot, no install
npx @voidly/pay-cli help

60-second start

# One command: mints a keypair, registers it, claims the 10-credit starter,
# prints your balance. Idempotent — safe to re-run.
voidly-pay claim

That writes ~/.voidly-pay/keypair.json (mode 0600). The key never leaves your machine; transfers are Ed25519-signed locally and the server verifies the signature.

voidly-pay whoami            # DID, public key, balance
voidly-pay transfer did:voidly:bob 0.5 --memo 'first payment'
voidly-pay history --limit 20

pay-curl — paying a 402 without writing code

pay-curl https://api.example.com/paid-endpoint          # paid GET, prints the body
pay-curl -X POST https://api.example.com/x -d '{"a":1}' # paid POST
pay-curl --max-amount 0.05 https://api.example.com/x    # refuse to pay more than this
pay-curl --claim                                        # claim the starter credits
pay-curl --balance

--max-amount is a hard cap per request: if the 402 challenge asks for more, pay-curl refuses and exits non-zero rather than paying. Set it on anything unattended.

Commands

Run voidly-pay help for the authoritative list — the binary's own help is generated from the dispatch table, so it cannot drift from what the code does. This README can; if the two disagree, the binary is right.

Onboarding

voidly-pay claim         # register + faucet + balance, idempotent. Start here.
voidly-pay faucet        # starter credits only (one-shot per DID)
voidly-pay register      # register this DID's pubkey (rare — claim does it)
voidly-pay whoami
voidly-pay balance [--did DID]

Moving credits

voidly-pay transfer <to> <amount> [--memo M]
voidly-pay batch did:voidly:a=1,did:voidly:b=2.5,did:voidly:c=0.1   # atomic
voidly-pay history [--did DID] [--limit N]

Escrow, streams, subscriptions

voidly-pay escrow open <to> <amount> [--hours H]
voidly-pay escrow release <id>
voidly-pay escrow refund <id> [--reason R]

voidly-pay stream open <provider> <budget>            # locks budget, returns stream_id
voidly-pay stream meter <stream_id> <seq> <delta> [--prev HASH] [--units N]
voidly-pay stream finalize <stream_id> <expected_seq> <metered_total_micro> [--prev HASH]

voidly-pay subscribe <provider> <amount/period> <period_seconds>
voidly-pay cancel-sub <subscription_id>

x402

# Client side: GET a URL and pay whatever 402 it returns, up to --max
voidly-pay fetch <url> [--max AMOUNT]

# Server side: mint a quote, verify an incoming X-Payment header
voidly-pay x402 quote <resource> <amount>
voidly-pay x402 verify '<header>'

Discovery and read-only state

voidly-pay marketplace   # every listed paid endpoint (public, no auth)
voidly-pay manifest      # discovery manifest for agents
voidly-pay health        # system-frozen flag + counts
voidly-pay stats
voidly-pay activity [--limit N]
voidly-pay leaderboard [--metric earned_24h] [--limit N]
voidly-pay feed [--since ISO] [--limit N]     # incremental indexer feed
voidly-pay trust [--did DID]
voidly-pay health-check [--rpc URL] [--skip-chain]   # one-call trust report

Webhooks

voidly-pay webhook subscribe https://my-server.com/voidly --events transfer.settled
voidly-pay webhook delete <id>

# Verify a delivery signature offline — no network, no keys on the wire
echo '{"foo":"bar"}' | voidly-pay verify-sig <secret_hex> 't=1234,v1=...'

All commands print JSON to stdout. Pipe through jq, or pass --pretty. Failures print to stderr and exit non-zero, so set -e scripts behave.

Configuration

export VOIDLY_PAY_API_URL=https://api.voidly.ai        # default
export VOIDLY_PAY_KEY_PATH=$HOME/.voidly-pay/keypair.json

Or per call: voidly-pay whoami --api-url http://localhost:8787.

Every command honours --api-url, including marketplace — before 1.0.4 that one command hardcoded production, so pointing the CLI at a local worker silently read live data instead.

What credits are, plainly

Credits are an internal accounting unit. They are not backed, not redeemable, and there is no off-ramp. Stage 2 — which would have backed them with USDC — is being retired (decided 2026-08-04); the vault on Base mainnet (0xd25d3c6f…) stays on-chain as a public record at voidly.ai/pay/proof, not as a reserve. Earlier releases of this package said otherwise; that claim is retracted.

Voidly Pay has approximately zero sustained external paying users. voidly-pay marketplace may well return an empty list today — the rail works, the supply side is new. If you list a capability on it, you will be early rather than lost in a crowd.

License

MIT