Pay For Service

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.

intent

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.

inputs

• fdx CLI: installed and accessible in bash. required for all wallet commands.
• Finance District wallet: must be initialized and authenticated. run fdx status to verify. if not authenticated, complete the authenticate skill first.
• wallet balance: funds in the payment asset on the target blockchain. confirm with fdx call getWalletOverview before attempting payment.
• x402 endpoint URL: the HTTP endpoint serving paid content, must support the x402 protocol (returns 402 when payment is required).
• optional preferences: preferred network (chain ID or name), preferred asset (token symbol), max payment amount in smallest unit.
• network connectivity: stable outbound HTTPS to the x402 endpoint and the Finance District payment facilitator. timeouts typically occur after 30 seconds.

procedure

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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).

7. 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.

decision points

• 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.

output contract

• 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.

outcome signal

• user receives the purchased content (full content body from the endpoint) and confirmation that payment cleared.
• wallet balance is reduced by the payment amount in the specified asset on the specified network.
• user can independently verify the transaction on-chain by querying the facilitator address or checking block explorer (if applicable to the chosen network).
• if an error occurs, the user receives a clear error message, an explanation of why it failed, and a suggested next step (authenticate, fund wallet, try different network, etc.).

how x402 works

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.

comparison to coinbase x402

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.

examples

# 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

prerequisites

• fdx CLI installed and in PATH.
• Finance District wallet authenticated. verify with fdx status.
• wallet holds sufficient balance in the payment asset on the target network.
• outbound HTTPS access to the endpoint and Finance District facilitator.

edge cases and error handling

• "not authenticated": run fdx setup or complete the authenticate skill.
• "insufficient balance": check balance with fdx call getWalletOverview. use fund-wallet skill to deposit or swap-tokens skill to exchange tokens.
• "no x402 payment requirements found": the URL may not support x402, or the server is not configured to return 402 responses. verify the URL is correct and that the endpoint operator supports x402.
• "payment rejected" or "payment failed": the wallet may lack balance, the payment proof may have expired (> 60 seconds old), or the facilitator rejected the signature. retry once; if it fails again, try a different preferred network or contact the service provider.
• network timeout (no response after 30 seconds): transient network issue or the endpoint is slow. retry once, or try a different preferred network. if retries fail, the endpoint may be down.
• unsupported network or asset: the endpoint does not accept payment in the asset or on the network you specified. retry without preferences, or ask the user to check the endpoint documentation for supported chains and tokens.
• rate limiting: if the endpoint returns HTTP 429 (too many requests), wait 60 seconds and retry. do not proceed if the user has exceeded the endpoint's rate limit.