polymer-pay-cli

name	polymer-pay-cli
description	USE THIS SKILL WHEN: the user wants to install polymerpay, authenticate with Polymer Pay, make paid x402 proxy requests from the command line, set up API keys, check their identity, or troubleshoot polymerpay CLI issues. Also trigger when the user mentions polymerpay, polymer-pay login, x402 payments, paid API calls, or wants to call any x402-protected endpoint through the CLI.
endpoints	[{"path":"polymerpay login","method":"CLI","price":"$0.00","description":"OAuth device flow authentication"},{"path":"polymerpay whoami","method":"CLI","price":"$0.00","description":"Print current authenticated user"},{"path":"polymerpay logout","method":"CLI","price":"$0.00","description":"Revoke session and clear credentials"},{"path":"polymerpay <url>","method":"CLI","price":"Varies","description":"Proxy request — price depends on upstream endpoint"}]
metadata	{"polymer-pay-skill":{"emoji":"💻","requires":{"env":[]}}}
registries	{}
provider	dynamic

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