name	walletconnect-pay
description	Manages the walletconnect-pay CLI for creating and completing WalletConnect Pay payments from the terminal. Use when the user wants to create a payment, check payment status, or complete a checkout with a connected wallet.

WalletConnect Pay CLI (Experimental)

This package is experimental. APIs and CLI interfaces may change significantly between releases. Use at your own risk.

Goal

Operate the walletconnect-pay CLI to create payments, check payment status, and complete checkout flows using a connected wallet.

When to use

User asks to create a WalletConnect Pay payment
User asks to check the status of a payment
User asks to pay or checkout a payment with their wallet
User mentions walletconnect-pay or WalletConnect Pay
User wants to complete a payment flow end-to-end

When not to use

User wants basic wallet connection without payments (use walletconnect skill)
User wants to stake WCT tokens (use walletconnect-staking skill)
User is working on the pay-cli source code (just edit normally)

Prerequisites

Binary is at packages/pay-cli/dist/cli.js (or globally linked as walletconnect-pay)
Build first if needed: npm run build -w @walletconnect/pay-cli
A connected CWP wallet provider is required for checkout (the walletconnect CLI must be installed)

Authentication modes

The CLI supports two modes:

Proxy mode (default, no API keys needed)

Routes requests through the WalletConnect Pay frontend. Used automatically when WC_PAY_WALLET_API_KEY is not set, or when --proxy is passed.

Direct API mode

Requires environment variables:

# Required for all direct API calls
export WC_PAY_WALLET_API_KEY=<wallet-api-key>

# Required only for merchant operations (create)
export WC_PAY_PARTNER_API_KEY=<partner-api-key>
export WC_PAY_MERCHANT_ID=<merchant-id>

Commands

# Check payment status
walletconnect-pay status <paymentId>
walletconnect-pay status <paymentId> --staging

# Create a new payment (requires merchant credentials)
walletconnect-pay create <amount>
walletconnect-pay create 1000 --unit iso4217/USD --staging

# Complete a payment with a connected wallet
walletconnect-pay checkout <paymentId>
walletconnect-pay checkout <paymentId> --staging --proxy

`status <paymentId>`

Read-only. Displays payment amount, merchant, status, and expiry.

Options:

--staging — Use the staging API
--proxy — Force proxy mode (no API keys needed)

`create <amount>`

Creates a new payment. Amount is in minor units (e.g. 1000 = $10.00).

Options:

--unit <string> — Currency unit (default: iso4217/USD)
--reference-id <string> — Merchant/PSP order ID
--staging — Use the staging API
--proxy — Force proxy mode

`checkout <paymentId>`

Full checkout flow: fetches payment → connects wallet → gets payment options → signs transaction → submits compliance data → confirms → polls for result.

Options:

--wallet <string> — Use a specific CWP wallet provider
--staging — Use the staging API
--proxy — Force proxy mode
--name <string> — Full legal name (Travel Rule compliance)
--dob <string> — Date of birth YYYY-MM-DD (Travel Rule compliance)
--pob-country <string> — Place of birth country code, e.g. US (ISO 3166-1 alpha-2)
--pob-address <string> — Place of birth city/state, e.g. 'New York, NY'

Travel Rule data can also be set via environment variables:

export WC_PAY_NAME="John Doe"
export WC_PAY_DOB="1990-01-15"
export WC_PAY_POB_COUNTRY="US"
export WC_PAY_POB_ADDRESS="New York, NY"

Default workflow

Check a payment

Run walletconnect-pay status <paymentId>
Display the result to the user

Create and pay (end-to-end)

Create a payment: walletconnect-pay create 100 --staging
Note the payment ID from the output
Checkout: walletconnect-pay checkout <paymentId> --staging --name "..." --dob "..." --pob-country "..." --pob-address "..."
Inform the user to approve the signing request in their wallet app
Wait for confirmation (the CLI polls automatically)

Important notes

Experimental: This CLI is under active development and may change significantly
Proxy mode: When no WC_PAY_WALLET_API_KEY is set, the CLI automatically routes through the frontend proxy — no API keys needed
Travel Rule compliance: Some payments require Information Capture (IC) data. The CLI will error with a clear message if --name, --dob, --pob-country, and --pob-address are missing when required
Wallet signing: The checkout command requires user interaction to approve signing requests in their wallet app. Use 60s+ timeouts
Staging vs production: Use --staging for testing. Production is the default
Amount format: The create command expects amounts in minor units (cents). 1000 = $10.00

Validation checklist

Binary is built and linked (walletconnect-pay --help works)
For direct API mode, environment variables are set
For checkout, a CWP wallet is installed and connected
Travel Rule data is provided when required (via flags or env vars)
Command output is shown to the user
Timeouts are 60s+ for wallet interaction commands

Examples

Check payment status

User: "What's the status of payment pay_abc123?"
Action: Run `walletconnect-pay status pay_abc123 --staging`

Create a $5 payment

User: "Create a $5 test payment"
Action: Run `walletconnect-pay create 500 --staging`
Note: 500 = $5.00 in minor units (cents)

Complete a payment

User: "Pay the payment pay_abc123"
Action: Run `walletconnect-pay checkout pay_abc123 --staging --name "John Doe" --dob "1990-01-15" --pob-country "US" --pob-address "New York, NY"`
Note: Inform user to approve the signing request in their wallet app. Use 60s+ timeout.

name	walletconnect-pay
description	Manages the walletconnect-pay CLI for creating and completing WalletConnect Pay payments from the terminal. Use when the user wants to create a payment, check payment status, or complete a checkout with a connected wallet.