ping-cli

CLI for Ping Checkout — crypto payments for AI agents and developers.

JSON-first output, env var overrides, and meaningful exit codes make it native to automation pipelines and AI agent workflows.

Install

# npm
npm install -g @pingpay/cli

# bun
bun install -g @pingpay/cli

# or run directly
npx @pingpay/cli status

Quick Start

# 1. Check the API is reachable
ping-cli status

# 2. Authenticate with your API key (get one from the Ping dashboard)
ping-cli init --api-key <your-key>

# 3. Verify auth
ping-cli whoami

# 4. Create a checkout session
ping-cli checkout create --amount 1000000 --asset-symbol USDC --asset-chain near

# 5. Create a payment link
ping-cli link create --name "My Store" --recipient-address "you.near" --asset-symbol USDC --asset-chain near

Commands

ping-cli init --api-key <key>

Store your API key in ~/.ping/config.json. Validates the key against the API before saving.

ping-cli init --api-key sk_live_abc123...

ping-cli status

Health check — no auth required. Returns { "status": "ok", "timestamp": "..." }.

ping-cli status
# Pipe to jq:
ping-cli status | jq .status

ping-cli whoami

Show current authentication info and payment count.

ping-cli whoami

ping-cli version

Print the CLI version.

ping-cli checkout create

Create a checkout session. Requires auth.

ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain near \
  --success-url "https://example.com/success" \
  --cancel-url "https://example.com/cancel" \
  --metadata '{"orderId": "123"}'

Flags: | Flag | Required | Description | |------|----------|-------------| | --amount | Yes | Amount in smallest units (e.g. 1000000 = 1 USDC) | | --asset-symbol | Yes | Token symbol: USDC, USDT, wnear, etc. | | --asset-chain | Yes | Blockchain: near, eth, etc. | | --success-url | No | Redirect URL on payment success | | --cancel-url | No | Redirect URL on cancel | | --metadata | No | JSON string of arbitrary metadata |

ping-cli checkout get <session-id>

Get a checkout session by ID. No auth required.

ping-cli checkout get cs_abc123

ping-cli payment get <payment-id>

Get payment details. Requires auth.

ping-cli payment get pay_abc123

ping-cli payment list

List payments with optional filters. Requires auth.

ping-cli payment list
ping-cli payment list --status SUCCESS --limit 10
ping-cli payment list --offset 50 --limit 25

Flags: | Flag | Default | Description | |------|---------|-------------| | --limit | 50 | Max results (1-100) | | --offset | 0 | Pagination offset | | --status | — | Filter: CREATED, PENDING, PROCESSING, SUCCESS, FAILED |

ping-cli payment wait <payment-id>

Poll a payment until it reaches a terminal state (SUCCESS, FAILED, REFUNDED). Requires auth.

# Wait up to 5 minutes (default)
ping-cli payment wait pay_abc123

# Custom timeout
ping-cli payment wait pay_abc123 --timeout 60

ping-cli link create

Create a payment link. Requires auth.

# Open amount — donors choose how much
ping-cli link create \
  --name "My Tip Jar" \
  --recipient-address "you.near" \
  --asset-symbol USDC \
  --asset-chain near

# Fixed amount
ping-cli link create \
  --name "Conference Ticket" \
  --description "Entry pass for the event" \
  --recipient-address "you.near" \
  --asset-symbol USDC \
  --asset-chain near \
  --amount-type fixed \
  --fixed-amount 50000000

Flags: | Flag | Required | Description | |------|----------|-------------| | --name | Yes | Link name (1-100 chars) | | --recipient-address | Yes | Wallet address to receive funds | | --asset-symbol | Yes | Token symbol: USDC, USDT, wnear, etc. | | --asset-chain | Yes | Blockchain: near, eth, etc. | | --amount-type | No | open (default) or fixed | | --fixed-amount | No | Amount in smallest units (required if fixed) | | --description | No | Link description (max 500 chars) |

ping-cli link list

List your payment links. Requires auth.

ping-cli link list
ping-cli link list --active true --limit 10

ping-cli link get <link-id>

Get a payment link by ID. Requires auth.

ping-cli link get pl_abc123

ping-cli link delete <link-id>

Delete a payment link. Requires auth.

ping-cli link delete pl_abc123

Configuration

Config file

ping-cli init saves to ~/.ping/config.json:

{
  "apiKey": "sk_live_...",
  "apiUrl": "https://pay.pingpay.io/api/rpc",
  "env": "production"
}

Environment variables

Override config file values:

| Variable | Description | |----------|-------------| | PING_API_KEY | API key | | PING_API_URL | API endpoint URL | | PING_ENV | production or development | | PING_OUTPUT | json (default) or pretty |

Priority

Flags > Environment variables > Config file > Defaults

Global flags

Every command accepts these flags:

| Flag | Description | |------|-------------| | --api-key | Override API key for this call | | --api-url | Override API URL for this call | | --output | json (default) or pretty |

Output

JSON mode (default): Machine-readable JSON to stdout. Errors to stderr.

ping-cli status
# {"status":"ok","timestamp":"2025-01-01T00:00:00Z"}

Pretty mode: Human-readable colored output.

ping-cli status --output pretty

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | User error (bad input, auth failure, not found) | | 2 | Server error (API down, network failure) |

ping-cli wallet create --email <email>

Create an AgentWallet — a crypto wallet your agent can use to send payments. A 6-digit OTP is sent to your email for verification.

# Interactive — prompts for OTP
ping-cli wallet create --email [email protected]

# Non-interactive — pass OTP directly
ping-cli wallet create --email [email protected] --otp 123456

Credentials are saved to ~/.ping/config.json. After creation, fund your wallet by sending USDC on Base to the returned evmAddress.

ping-cli wallet connect

Connect an existing AgentWallet. Auto-detects credentials from ~/.agentwallet/config.json if available, or pass them manually:

ping-cli wallet connect --token mf_... --username agent123 --evm-address 0x...

ping-cli wallet balance

Check wallet balances across chains.

ping-cli wallet balance

ping-cli pay --session-id <id>

Pay a checkout session in one command. Prepares the payment, sends funds from your connected wallet, and returns the transaction hash.

Currently supports USDC on Base only.

ping-cli pay --session-id cs_abc123

Flags: | Flag | Required | Default | Description | |------|----------|---------|-------------| | --session-id | Yes | — | Checkout session ID to pay | | --asset-symbol | No | USDC | Asset to pay with | | --asset-chain | No | base | Chain to pay on |

AI Agent Usage

ping-cli is designed for AI agents. Key patterns:

# Create a checkout and extract the session URL
SESSION_URL=$(ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain base | jq -r '.sessionUrl')

# Pay a checkout session
ping-cli pay --session-id cs_abc123

# Create a payment link and get the link URL
LINK_URL=$(ping-cli link create \
  --name "Payment" \
  --recipient-address "0xmerchant" \
  --asset-symbol USDC \
  --asset-chain base | jq -r '.linkUrl')

# Wait for payment completion in a script
ping-cli payment wait pay_abc123 --timeout 120
if [ $? -eq 0 ]; then
  echo "Payment succeeded"
fi

Development

# Run locally
bun run src/index.ts status

# Run tests
bun run test

# Type check
bun run typecheck

# Build for npm
bun run build

# Build standalone binary
bun run build:binary