Payment Troubleshooting

Common Issues

Insufficient USDC Balance

Error: payment_required or insufficient_payment

Symptoms: { "error": "insufficient_payment", "details": { "required": "0.01", "provided": "0.005" } }

Fix:

1. Check balance: https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913?a=YOUR_ADDRESS
2. Ad USDC via https://app.uniswap.org or Coinbase
3. Ensure USDC is on Base network

Wrong Network

Error: invalid_chain

Fix:

• Ensure wallet is on Base (Chain ID: 8453)
• Not Ethereum mainnet (1), not Arbitrum (42161)
• Bridge funds: https://bridge.base.org

Payment Expired

Error: payment_expired

Fix: x402 client handles this automatically. If using manual cURL:

1. Request fresh 402 from the endpoint
2. Sign new payment with current timestamp
3. Retry within the expires_at window

Rate Limited

Error: rate_limit_exceeded (HTTP 429)

Fix: import time time.sleep(response.json()['retry_after']) # Then retry the request

Invalid Signature

Error: invalid_payment

Fix:

1. Verify wallet private key is correct
2. Check wallet address matches the signing key
3. Ensure EIP-712 domain matches Base USDC contract

Gas Issues

Symptom: Payment signed but transaction fails on-chain

Fix:

1. Add a small amount of Base ETH for gas (~$0.10)
2. Get Base ETH from: https://bridge.base.org

Debug Mode

Enable verbose logging to see the full payment flow:

import logging
logging.basicConfig(level=logging.DEBUG)

client = X402Client(wallet=wallet, debug=True)

# You will see:
# DEBUG: Requesting GET /price/ETH
# DEBUG: Received 402 Payment Required
# DEBUG: Payment requirements: amount=10000, token=USDC, network=base
# DEBUG: Signing EIP-712 payment...
# DEBUG: Retrying with payment proof
# DEBUG: Payment verified, serving data
# DEBUG: Response 200 OK

Testing Without Spending

Free Endpoints

# These are always free, no wallet needed
curl https://api.foursec.xyz/health
curl https://api.foursec.xyz/

Testnet (Coming Soon)

A Base Sepolia testnet version will be available for testing with testnet USDC.

Network Issues

Connection Timeout

# Check if API is reachable
curl -v https://api.foursec.xyz/health

# If timeout, check:
# 1. Internet connection
# 2. Firewall rules (allow port 443 outbound)
# 3. DNS resolution: nslookup api.foursec.xyz

Slow Responses

# Check latency
curl -w "Time: %{time_total}s\n" -o /dev/null -s https://api.foursec.xyz/health

# Expected: < 200ms from most locations
# If slow, consider self-hosting a facilitator

Still Having Issues?

1. Check status page: https://status.foursec.xyz
2. Open GitHub issue: https://github.com/foursec/issues
3. Join Discord: https://discord.gg/foursec
4. Email: support@foursec.xyz

Include these details:

• Wallet address (not private key!)
• Error response body
• Timestamp of the error
• Your location/region