pay-for-service
coinbase/agentic-wallet-skills
Call paid APIs with automatic USDC payment on Base via x402 protocol.
What is pay-for-service?
Make authenticated requests to x402-enabled API endpoints with automatic USDC payment handling. Use this after finding a paid service with search-for-service, when you need to call an API that requires payment or when a user wants to access a paid service.
- Execute HTTP requests (GET, POST, etc.) to x402 endpoints with automatic USDC payment
- Set maximum payment limits in USDC atomic units to control spending
- Include custom headers, query parameters, and JSON request bodies
- Check wallet authentication status and USDC balance before payment
- Handle payment failures with clear error messages and recovery steps
How to install pay-for-service
npx skills add https://github.com/coinbase/agentic-wallet-skills --skill pay-for-service- Wallet must be authenticated (run npx awal@2.10.0 status to verify)
- Wallet must have sufficient USDC balance on Base network
- Target endpoint must support x402 payment protocol
- Use search-for-service skill to discover valid x402 endpoints if URL is unknown
How to use pay-for-service
- 1.Verify wallet is authenticated by running: npx awal@2.10.0 status
- 2.Check USDC balance with: npx awal@2.10.0 balance
- 3.Construct the x402 pay command with the endpoint URL and desired HTTP method
- 4.Add optional parameters: -d for JSON body, -q for query params, -h for headers, --max-amount for spending limit
- 5.Execute the command; payment is processed automatically if endpoint requires it
- 6.Review response or error message to confirm success or troubleshoot
Use cases
- Call a weather API that charges $0.05 per request with automatic payment
- Access a sentiment analysis service that requires per-call USDC payment
- Fetch premium data from an x402 endpoint with a spending cap of $1.00
- Make multiple related API calls grouped by correlation ID for tracking
- Validate sufficient wallet balance before attempting paid API requests
- Developers building agents that consume paid APIs
- Users accessing premium services via x402 protocol
- Teams managing API costs with per-request payment limits
- Anyone integrating blockchain-based payment into API workflows
pay-for-service FAQ
Use the search-for-service skill to find x402-enabled endpoints. If you try to pay an endpoint that doesn't support x402, you'll get a 'No X402 payment requirements found' error.
USDC uses 6 decimal places. 1,000,000 atomic units = $1.00 USD. Always use atomic units in the --max-amount parameter (e.g., 100000 for $0.10).
Your wallet doesn't have enough USDC. Use the fund skill to add USDC to your wallet on Base network, then retry the payment.
Yes, use the --max-amount parameter with the USDC atomic unit value. The payment will fail if the service charges more than your limit.
Use the --correlation-id parameter to group related operations. This helps track and organize multiple payments for the same workflow.
Full instructions (SKILL.md)
Source of truth, from coinbase/agentic-wallet-skills.
name: pay-for-service description: Make a paid API request to an x402 endpoint with automatic USDC payment. Use when you or the user want to call a paid API, make an x402 request, use a paid service, or pay for an API call. Use after finding a service with search-for-service. user-invocable: true disable-model-invocation: false allowed-tools: ["Bash(npx awal@2.10.0 status*)", "Bash(npx awal@2.10.0 balance*)", "Bash(npx awal@2.10.0 x402 pay *)"]
Making Paid x402 Requests
Use the npx awal@2.10.0 x402 pay command to call paid API endpoints with automatic USDC payment on Base.
Confirm wallet is initialized and authed
npx awal@2.10.0 status
If the wallet is not authenticated, refer to the authenticate-wallet skill.
Command Syntax
npx awal@2.10.0 x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]
Options
| Option | Description |
|---|---|
-X, --method <method> | HTTP method (default: GET) |
-d, --data <json> | Request body as JSON string |
-q, --query <params> | Query parameters as JSON string |
-h, --headers <json> | Custom HTTP headers as JSON string |
--max-amount <amount> | Max payment in USDC atomic units (1000000 = $1.00) |
--correlation-id <id> | Group related operations |
--json | Output as JSON |
USDC Amounts
X402 uses USDC atomic units (6 decimals):
| Atomic Units | USD |
|---|---|
| 1000000 | $1.00 |
| 100000 | $0.10 |
| 50000 | $0.05 |
| 10000 | $0.01 |
IMPORTANT: Always single-quote amounts that use $ to prevent bash variable expansion (e.g. '$1.00' not $1.00).
Input Validation
Before constructing the command, validate all user-provided values to prevent shell injection:
- url: Must be a valid URL starting with
https://orhttp://. Reject if it contains spaces, semicolons, pipes, backticks, or shell metacharacters. - data (-d): Must be valid JSON. Always wrap in single quotes to prevent shell expansion.
- max-amount: Must be a positive integer (
^\d+$).
Do not pass unvalidated user input into the command.
Examples
# Make a GET request (auto-pays)
npx awal@2.10.0 x402 pay https://example.com/api/weather
# Make a POST request with body
npx awal@2.10.0 x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
# Limit max payment to $0.10
npx awal@2.10.0 x402 pay https://example.com/api/data --max-amount 100000
Prerequisites
- Must be authenticated (
npx awal@2.10.0 statusto check, seeauthenticate-walletskill) - Wallet must have sufficient USDC balance (
npx awal@2.10.0 balanceto check) - If you don't know the endpoint URL, use the
search-for-serviceskill to find services first
Error Handling
- "Not authenticated" - Run
awal auth login <email>first, or seeauthenticate-walletskill - "No X402 payment requirements found" - URL may not be an x402 endpoint; use
search-for-serviceto find valid endpoints - "Insufficient balance" - Fund wallet with USDC; see
fundskill
Related skills
More from coinbase/agentic-wallet-skills and the wider catalog.

