polymerdao/polymer-pay-cli

polymerpay CLI

Command-line tool for calling x402-protected API endpoints through the Polymer Pay proxy. The proxy handles payment negotiation and settlement automatically — you authenticate, and Polymer Pay charges your account credits.

Install

Check if polymerpay is already installed before installing:

polymerpay --version || npm install -g @polymer-pay.ai/polymerpay

Authentication

Device Flow Login (recommended)

No pre-registration needed. Run polymerpay login and you'll be guided through account creation and authentication in your browser via OAuth device flow.

polymerpay login

This prints a URL and a device code, then opens your browser. If you don't have an account yet, you'll create one during the browser flow. Once approved, credentials are saved to ~/.polymer-pay/credentials.json (file mode 0600). Tokens auto-refresh on subsequent requests.

Check who you're logged in as:

polymerpay whoami

Re-authenticate (force a fresh login even if already logged in):

polymerpay login --force

Log out (revokes tokens and deletes local credentials):

polymerpay logout

API Key (for scripts and non-interactive agents)

If you already have an Polymer Pay account and an API key (from https://app.polymer-pay.ai), you can skip the login step entirely:

{
  "headers": {
    "Content-Type": "application/json",
    "x-polymer-pay-api-key": "{{POLYMER_PAY_API_KEY}}"
  }
}

Set it in your environment:

export POLYMER_PAY_API_KEY="your-api-key"

When POLYMER_PAY_API_KEY is set, polymerpay uses it automatically — no polymerpay login needed.

Auth Precedence

When making a proxy request, polymerpay resolves auth in this order:

1. POLYMER_PAY_API_KEY environment variable (if set)
2. OAuth token from ~/.polymer-pay/credentials.json (auto-refreshes if expired)
3. Error if neither is available

Base URL: https://pay.polymerlabs.org/proxy/{scheme}/{host}

Common Operations

GET Request

Fetch data from any x402-protected endpoint.

Pricing: Varies based on upstream endpoint

polymerpay https://api.example.com/v1/resource

The proxy rewrites the URL internally as https://pay.polymerlabs.org/proxy/https/api.example.com/v1/resource, authenticates you, and forwards the request with payment handling.

POST with JSON Data

Send data to an x402-protected endpoint.

Pricing: Varies based on upstream endpoint

polymerpay -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "your data"}' \
  https://api.example.com/v1/resource

If you pass -d without -X, the method defaults to POST automatically:

polymerpay -d '{"query": "your data"}' https://api.example.com/v1/resource

Custom Headers

Add request headers (repeatable).

polymerpay -H "Content-Type: application/json" \
  -H "X-Custom: value" \
  https://api.example.com/v1/resource

Verbose Output

Debug requests with increasing verbosity levels.

# Show response status and headers
polymerpay -v https://api.example.com/v1/resource

# Show full request + response
polymerpay -vv https://api.example.com/v1/resource

When to Use

• CLI-based x402 access — Call any x402-protected API from the terminal without writing code.
• Agent setup — Install, login once, and make paid API calls immediately.
• Quick testing — Verify x402 endpoints work before integrating into an application.
• Script automation — Use POLYMER_PAY_API_KEY for non-interactive paid API calls in CI or cron jobs.

Best Practices

1. Use device flow for first-time setup — polymerpay login handles registration and authentication in one step. No need to create an account separately.
2. Use API keys for automation — Store POLYMER_PAY_API_KEY in env vars for scripts, CI, and non-interactive agents.
3. Debug with -vv — Shows full request and response details when something goes wrong.
4. Never expose credentials — Keep POLYMER_PAY_API_KEY secure. Credentials at ~/.polymer-pay/credentials.json are stored with restricted file permissions (0600).
5. For errors — See @skills/polymer-pay-api-errors/SKILL.md for complete error code reference and troubleshooting

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | POLYMER_PAY_API_KEY | — | API key for proxy auth (skips OAuth) | | POLYMER_PAY_PROXY_URL | https://pay.polymerlabs.org/proxy | Override proxy base URL | | POLYMER_PAY_ISSUER_URL | https://api.polymer-pay.ai | Override OAuth issuer URL |

Quick Reference

polymerpay login                    # authenticate (device flow + registration)
polymerpay login --force            # re-authenticate
polymerpay whoami                   # print current user
polymerpay logout                   # revoke and clear credentials
polymerpay <url>                    # GET through proxy
polymerpay -X POST -d <body> <url> # POST through proxy
polymerpay -H "Key: Val" <url>     # add headers
polymerpay -v <url>                 # verbose response
polymerpay -vv <url>                # verbose request + response
polymerpay --version                # print version
polymerpay --help                   # show help