Access paid API endpoints and content using the x402 payment protocol. Use when you or the user want to call a paid API, access gated content, make an x402 p...
--- name: pay-for-service description: Access paid API endpoints and content using the x402 payment protocol. Use when you or the user want to call a paid API, access gated content, make an x402 payment, use a paid service, or retrieve content that requires payment. Covers "fetch this paid resource", "access x402 content", "pay for this API call". user-invocable: true disable-model-invocation: false allowed-tools: ["Bash(fdx status*)", "Bash(fdx call getX402Content*)", "Bash(fdx call authorizePayment*)", "Bash(fdx call getWalletOverview*)"] --- # Paying for Services (x402) Use the Finance District wallet to access paid API endpoints and gated content via the x402 HTTP payment protocol. The wallet handles payment authorization and signing automatically — the agent fetches the content in a single call. ## How x402 Works x402 is an HTTP-native payment protocol: 1. A server returns HTTP 402 with payment requirements 2. The wallet signs a payment and retries the request with a payment header 3. The facilitator verifies and settles the payment 4. The server returns the content The Finance District wallet supports x402 payments on multiple chains and assets, not just a single network. ## Confirm wallet is authenticated ```bash fdx status ``` If the wallet is not authenticated, refer to the `authenticate` skill. ## Check Balance Ensure the wallet has sufficient funds to cover the payment: ```bash fdx call getWalletOverview ``` ## Fetching Paid Content ### getX402Content — Fetch content from a paid endpoint The primary command for accessing x402 resources. It discovers payment requirements, authorizes payment, and retrieves the content in one step: ```bash fdx call getX402Content --url <endpoint-url> ``` #### Parameters | Parameter | Required | Description | | ------------------------ | -------- | ----------------------------------------------------- | | `--url` | Yes | The x402-enabled endpoint URL | | `--preferredNetwork` | No | Preferred chain ID for payment (e.g. `8453` for Base) | | `--preferredNetworkName` | No | Preferred chain name (e.g. `base`, `ethereum`) | | `--preferredAsset` | No | Preferred payment asset (e.g. `USDC`) | | `--maxPaymentAmount` | No | Maximum payment amount to authorize | ### authorizePayment — Pre-authorize a payment For cases where you want to inspect payment requirements or authorize without fetching: ```bash fdx call authorizePayment --url <endpoint-url> ``` #### Parameters Same as `getX402Content`. ## Examples ```bash # Fetch content from a paid API (auto-discovers requirements and pays) fdx call getX402Content \ --url https://api.example.com/premium/data # Prefer paying with USDC on Base fdx call getX402Content \ --url https://api.example.com/premium/data \ --preferredNetworkName base \ --preferredAsset USDC # Set a max payment cap fdx call getX402Content \ --url https://api.example.com/premium/data \ --maxPaymentAmount 1000000 # Just authorize without fetching fdx call authorizePayment \ --url https://api.example.com/premium/data ``` ## Flow 1. Check authentication with `fdx status` 2. Check wallet balance with `fdx call getWalletOverview` 3. Call `fdx call getX402Content --url <endpoint>` to fetch paid content 4. If the payment amount seems high, use `fdx call authorizePayment` first to inspect, then confirm with the human before proceeding 5. Return the fetched content to the human **Important:** Always inform your human about the payment before executing, especially for unfamiliar endpoints or amounts that seem high. Let them confirm they want to proceed. ## Difference from Coinbase x402 The Finance District wallet supports **multi-chain and multi-asset** x402 payments. You can specify a preferred network and asset, giving flexibility to pay from whichever chain and token has available balance. Coinbase's implementation is limited to Base USDC. ## Prerequisites - Must be authenticated (`fdx status` to check, see `authenticate` skill) - Wallet must have sufficient balance in the required payment asset on the required network - If insufficient funds, suggest using the `fund-wallet` skill or `swap-tokens` skill ## Error Handling - "Not authenticated" — Run `fdx setup` first, or see `authenticate` skill - "Insufficient balance" — Check balance; see `fund-wallet` skill - "No x402 payment requirements found" — The URL may not be an x402-enabled endpoint - "Payment failed" — May be a network issue; retry or try a different preferred network
don't have the plugin yet? install it then click "run inline in claude" again.
restructured into six implexa components with explicit decision points, edge cases, error codes, and input requirements. clarified the x402 protocol, wallet setup dependencies, multi-chain support, and user consent flow. added decision tree for authentication, balance, payment inspection, and failure recovery.
Use the Finance District wallet to access paid API endpoints and gated content via the x402 HTTP payment protocol. invoke this skill when a user or agent needs to fetch content behind a payment wall, call a paid API, or settle an x402 charge. the wallet handles payment authorization and signing automatically in a single request.
this skill lets you pay for and retrieve content from x402-enabled endpoints without manual wallet interaction. the x402 protocol is an HTTP standard where a server returns a 402 payment required response with terms, the wallet signs a payment proof, and the request retries with proof in the headers. use this skill anytime a resource requires payment upfront, when you need to set asset or network preferences, or when you want to inspect payment requirements before committing funds. multi-chain and multi-asset support means you can specify which blockchain and token to use for payment.
fdx status to verify. if not authenticated, complete the authenticate skill first.fdx call getWalletOverview before attempting payment.verify wallet authentication. run fdx status to confirm the wallet is authenticated. output: status string including wallet address and auth state. if status shows "not authenticated", stop and defer to the authenticate skill.
check wallet balance. run fdx call getWalletOverview to retrieve available balance across all networks and assets. output: JSON object with balance breakdown by network and token. if the required asset has zero balance on the target network, proceed to step 3; otherwise continue to step 5.
handle insufficient balance (decision point, see section 4). if balance is insufficient, either suggest fund-wallet skill to deposit funds, or suggest swap-tokens skill to exchange existing balance into the required asset. do not proceed to step 5 until balance is confirmed.
inform the user about payment intent. before fetching paid content, communicate to the human: the endpoint URL, estimated or required payment amount (if known), network/asset preferences, and max amount cap if set. request explicit confirmation to proceed. output: user acknowledgment message. if user declines, stop here.
authorize payment (optional inspection step). run fdx call authorizePayment --url <endpoint-url> with optional network and asset flags to inspect payment requirements without fetching content. output: JSON with payment amount, asset, network, and facilitator address. review output; if amount exceeds user's stated max or seems unexpected, loop back to step 4 for re-confirmation.
fetch paid content. run fdx call getX402Content --url <endpoint-url> with all user-specified preferences (network name, asset, max amount). the wallet discovers payment requirements from a 402 response, signs the payment, and retries the request with the signed proof in headers. output: the requested content from the server (format depends on endpoint, typically JSON, binary, or text).
confirm successful retrieval. if the HTTP status is 200 or 201, the payment succeeded and content was returned. output: the content itself plus a confirmation that payment was settled. if HTTP status is 402 after retry, payment was rejected (see error handling, section 5). if timeout or connection error, retry once with a different preferred network if provided.
wallet authentication state: if fdx status shows "not authenticated", do not proceed. user must complete authenticate skill first.
insufficient balance: if fdx call getWalletOverview shows zero or insufficient balance in the payment asset on the target network, offer two paths: (a) use fund-wallet to deposit new funds, or (b) use swap-tokens to exchange another asset into the required token. do not attempt payment until balance is confirmed.
user consent before payment: always inform the user of the endpoint URL, payment amount, and network/asset choice before executing getX402Content. require explicit confirmation. if user declines or asks to set a lower max amount, apply the cap and retry authorization (step 5).
payment amount inspection: if the payment required exceeds the user's stated maximum or seems disproportionate to the content value, call authorizePayment first to show the breakdown, then re-confirm with the user before calling getX402Content.
network or asset unavailability: if the preferred network or asset is not supported by the endpoint, the facilitator will return an error. retry with a different preferred network (e.g. switch from Ethereum to Base) or without network/asset preference to let the wallet choose.
content retrieval failure after payment: if the request returns 402 again after payment (or a different error status), the payment may have been rejected or the endpoint may be misconfigured. do not retry payment; instead ask the user to verify the endpoint URL and contact the service provider.
successful retrieval: HTTP 200 or 201 with content body. content format varies by endpoint (JSON, binary, text, etc.). always include a statement that payment was authorized and settled, with the amount charged and asset/network used.
payment inspection (authorizePayment step): JSON object with fields paymentAmount (integer, smallest unit of asset), asset (string, token symbol), network (integer chain ID or string name), facilitatorAddress (Ethereum address), and expiresAt (Unix timestamp for payment proof validity).
error output: JSON or string with error code and message. expected error codes: "NOT_AUTHENTICATED", "INSUFFICIENT_BALANCE", "NO_X402_ENDPOINT", "PAYMENT_REJECTED", "NETWORK_TIMEOUT", "UNSUPPORTED_NETWORK", "UNSUPPORTED_ASSET". see error handling section for remediation.
x402 is an HTTP-native payment protocol. a server returns HTTP 402 with payment requirements in headers. the client signs a payment proof, retries the request with the proof in headers, and the server returns the content. Finance District wallet supports multi-chain and multi-asset payments, not just a single network. you can specify preferred network and asset; the wallet will use that if available, or return an error if the endpoint does not support it.
Finance District supports multi-chain (Ethereum, Base, Polygon, etc.) and multi-asset (USDC, ETH, etc.) x402 payments. Coinbase x402 is limited to Base USDC. choose Finance District if you need payment flexibility across networks or assets.
# fetch content from a paid API (auto-discovers requirements and pays)
fdx call getX402Content \
--url https://api.example.com/premium/data
# prefer paying with USDC on Base
fdx call getX402Content \
--url https://api.example.com/premium/data \
--preferredNetworkName base \
--preferredAsset USDC
# set a max payment cap (in smallest unit, e.g. cents for USDC)
fdx call getX402Content \
--url https://api.example.com/premium/data \
--maxPaymentAmount 1000000
# inspect payment requirements without fetching
fdx call authorizePayment \
--url https://api.example.com/premium/data \
--preferredNetworkName base
fdx status.fdx setup or complete the authenticate skill.fdx call getWalletOverview. use fund-wallet skill to deposit or swap-tokens skill to exchange tokens.