pay-for-http-request

by stripe

Make HTTP requests with automatic x402 payment support using the purl command line interface. npx skills add https://github.com/stripe/purl --skill pay-for-http-request Download ZIPGitHub174

pay-for-http-request

Make HTTP requests with automatic x402 payment support using purl.

Description

This skill enables making HTTP requests to payment-gated APIs using purl, a curl-like CLI tool that automatically handles x402-based payments on EVM and Solana networks.

When to Use This Skill

When an API returns HTTP 402 (Payment Required) and supports the x402 payment protocol, purl can automatically negotiate and execute the payment to access the resource.

Common Scenarios

Scenario Example Tool calls Paying per request to an API service Premium data feeds Accessing real-time market data, weather, or analytics Content monetization Paying to access paywalled articles or media Compute resources On-demand access to compute or storage services

When NOT to Use

• Regular HTTP requests that don't require payment (use curl instead)

• APIs using traditional payment methods (credit cards, API keys with billing)

Commands

Command Description wallet Manage wallets (keystores) config Manage configuration balance Check wallet balance inspect Inspect payment requirements without executing networks Manage and inspect supported networks version Show version information completions Generate shell completions script topics Display help topics (exit-codes, formatting, examples, environment)

Request Options

Payment Options

Option Description --max-amount <AMOUNT> Maximum amount willing to pay (in atomic units) --confirm Require confirmation before paying --network <NETWORKS> Filter to specific networks (comma-separated) --dry-run Preview payment without executing

Display Options

Option Description -v, --verbosity Verbosity level (can be used multiple times: -v, -vv, -vvv) -q, --quiet / -s, --silent Do not print log messages -i, --include Include HTTP headers in output -I, --head Show only HTTP headers -o, --output <FILE> Write output to file --output-format <FORMAT> Output format: auto, text, json, yaml (auto detects: text for terminal, json for pipes) --color <MODE> Control color output: auto, always, never

HTTP Options

Option Description -X, --request <METHOD> Custom request method -H, --header <HEADER> Add custom header -A, --user-agent <AGENT> Set user agent -L, --location Follow redirects --connect-timeout <SECONDS> Connection timeout in seconds -m, --max-time <SECONDS> Maximum time for the request -d, --data <DATA> POST data --json <JSON> Send JSON data with Content-Type header

Wallet Options

Option Description --wallet <PATH> Path to wallet file --password <PASSWORD> Password for wallet decryption --private-key <KEY> Raw private key (hex, for EVM; use wallet for better security)

Global Options

Option Description -C, --config <PATH> Configuration file path

Wallet Commands

purl wallet 

Command Description list List available wallets add Create a new wallet (interactive) show <NAME> Show wallet details verify <NAME> Verify wallet integrity use <NAME> Set a wallet as the active payment method remove <NAME> Remove a wallet

Wallet Add Options

Option Description -n, --name <NAME> Name for the wallet -t, --type <TYPE> Wallet type: evm or solana -k, --private-key <KEY> Private key to import (hex for EVM, base58 for Solana)

Config Commands

purl config [COMMAND]

Command Description (none) Show current config get <KEY> Get a specific configuration value (supports dot notation) validate Validate configuration file

Examples

Basic payment request

purl https://api.example.com/premium-data

Preview payment without executing

purl --dry-run https://api.example.com/data

Require confirmation before payment

purl --confirm https://api.example.com/data

Set maximum payment amount

purl --max-amount 10000 https://api.example.com/data

Filter to specific network

purl --network base-sepolia https://api.example.com/data

Verbose output with headers

purl -vi https://api.example.com/data

Save output to file as JSON

purl -o output.json --output-format json https://api.example.com/data

POST request with JSON data

purl --json '{"key": "value"}' https://api.example.com/data

Custom headers

purl -H "Authorization: Bearer token" https://api.example.com/data

Follow redirects with custom method

purl -L -X POST https://api.example.com/data

Check wallet balance

purl balance
purl balance --network base

Inspect payment requirements

purl inspect https://api.example.com/endpoint

Wallet management

purl wallet add # Interactive wallet creation
purl wallet add --type evm # Skip type selection
purl wallet add --type solana -k KEY # Import existing key
purl wallet list # List all wallets
purl wallet use my-wallet # Switch active wallet

View supported networks

purl networks
purl networks info base

Supported Networks

Type Networks EVM ethereum, ethereum-sepolia, base, base-sepolia, avalanche, avalanche-fuji, polygon, arbitrum, optimism SVM solana, solana-devnet

Environment Variables

Variable Description PURL_MAX_AMOUNT Default maximum amount willing to pay PURL_NETWORK Default network filter PURL_CONFIRM Default confirmation behavior (true/false) PURL_KEYSTORE Default wallet/keystore path PURL_PASSWORD Wallet password (for non-interactive use)

Usage

purl [OPTIONS]
purl 

Prerequisites

• Create a wallet: purl wallet add

• Set up a payment method (wallet) with funds on the desired network

• Ensure the target API supports x402 payment protocol