# x402 API Gateway - AI Agent Instructions

## What is this?

x402 API Gateway lets AI agents access multiple APIs with micropayments in USDC on Base blockchain. Pay $0.0001-$0.003 per request, no subscriptions.

## Quick Start

1. Check available APIs: GET /catalog
2. Make request without payment: GET /proxy/{apiId}/{path}
3. Receive 402 Payment Required with payment details
4. Send USDC payment on Base to gateway address
5. Retry request with Payment-Signature header
6. Receive API response

## Gateway Information

- Production URL: https://api.targe.io
- Network: Base Mainnet (eip155:8453)
- Payment Address: 0xBf9D8c0f5c25b7Dea1261333bb341f72bc1244E0
- USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Currency: USDC (6 decimals)

## Available APIs

### No Authentication Required

1. CoinGecko - Crypto prices ($0.001/request)
   - Example: /proxy/coingecko/ping
   - Example: /proxy/coingecko/simple/price?ids=bitcoin&vs_currencies=usd

2. Open-Meteo - Weather data ($0.0005/request)
   - Example: /proxy/openmeteo/forecast?latitude=40.7&longitude=-74&current_weather=true

3. REST Countries - Country information ($0.0005/request)
   - Example: /proxy/restcountries/name/usa
   - Example: /proxy/restcountries/all

4. IP-API - Geolocation ($0.001/request)
   - Example: /proxy/ipapi/json/8.8.8.8

5. ExchangeRate - Currency rates ($0.0005/request)
   - Example: /proxy/exchangerate/latest/USD

6. JokeAPI - Programming jokes ($0.0001/request)
   - Example: /proxy/jokeapi/joke/Programming

### Requires Your API Key (Bring Your Own Key)

7. OpenWeather - Weather data ($0.002/request)
   - Requires: X-Upstream-Auth header with your OpenWeather API key
   - Example: /proxy/openweather/weather?q=London

8. GitHub - Repository data ($0.003/request)
   - Requires: X-Upstream-Auth header with your GitHub token
   - Example: /proxy/github/users/octocat

## Payment Flow

### Step 1: Make Request Without Payment

```
GET https://api.targe.io/proxy/coingecko/ping
```

Response: 402 Payment Required
```json
{
  "error": "Payment required",
  "amount": "0.001",
  "currency": "USDC",
  "network": "eip155:8453",
  "paymentAddress": "0xBf9D8c0f5c25b7Dea1261333bb341f72bc1244E0"
}
```

### Step 2: Send USDC Payment

Send USDC on Base Mainnet to: 0xBf9D8c0f5c25b7Dea1261333bb341f72bc1244E0

Amount: Exact amount from step 1 (e.g., 0.001 USDC)

Save the transaction hash.

### Step 3: Create Payment Signature

```json
{
  "from": "0xYourWalletAddress",
  "to": "0xBf9D8c0f5c25b7Dea1261333bb341f72bc1244E0",
  "amount": "0.001",
  "network": "eip155:8453",
  "txHash": "0xYourTransactionHash",
  "timestamp": 1706356800000
}
```

Encode this JSON to base64.

### Step 4: Retry with Payment Signature

```
GET https://api.targe.io/proxy/coingecko/ping
Header: Payment-Signature: <base64-encoded-payment-json>
```

Response: 200 OK with API data

## Authentication for BYOK APIs

Some APIs require you to provide your own API key:

```
GET /proxy/openweather/weather?q=London
Header: X-Upstream-Auth: YOUR_OPENWEATHER_API_KEY
Header: Payment-Signature: <base64-payment>
```

The gateway will inject your key into the upstream request.

## Rate Limiting

Based on reputation score:
- Standard: 100 requests/minute
- Premium: 1000 requests/minute (high reputation agents)
- Throttled: 10 requests/minute (low reputation agents)

Build reputation by making successful paid requests.

## Example Code (TypeScript)

```typescript
// 1. Get payment requirements
const response1 = await fetch('https://api.targe.io/proxy/coingecko/ping');
const paymentInfo = await response1.json();

// 2. Send USDC payment on Base
const txHash = await sendUSDC(
  paymentInfo.paymentAddress,
  paymentInfo.amount
);

// 3. Create payment signature
const payment = {
  from: myWalletAddress,
  to: paymentInfo.paymentAddress,
  amount: paymentInfo.amount,
  network: 'eip155:8453',
  txHash: txHash,
  timestamp: Date.now()
};

const signature = btoa(JSON.stringify(payment));

// 4. Retry with payment
const response2 = await fetch('https://api.targe.io/proxy/coingecko/ping', {
  headers: {
    'Payment-Signature': signature
  }
});

const data = await response2.json();
console.log(data); // API response
```

## Example Code (Python)

```python
import requests
import json
import base64
import time

# 1. Get payment requirements
r1 = requests.get('https://api.targe.io/proxy/coingecko/ping')
payment_info = r1.json()

# 2. Send USDC payment on Base
tx_hash = send_usdc(payment_info['paymentAddress'], payment_info['amount'])

# 3. Create payment signature
payment = {
    'from': my_wallet_address,
    'to': payment_info['paymentAddress'],
    'amount': payment_info['amount'],
    'network': 'eip155:8453',
    'txHash': tx_hash,
    'timestamp': int(time.time() * 1000)
}

signature = base64.b64encode(json.dumps(payment).encode()).decode()

# 4. Retry with payment
headers = {'Payment-Signature': signature}
r2 = requests.get('https://api.targe.io/proxy/coingecko/ping', headers=headers)
data = r2.json()
print(data)  # API response
```

## Discovery

- ERC-8004 Agent Card: /.well-known/agent.json
- OpenAPI Spec: /openapi.json
- Gateway Stats: /stats
- API Catalog: /catalog

## Support

- Gateway Health: /health
- Documentation: https://api.targe.io
- Network: Base Mainnet (Chain ID: 8453)

## Notes for AI Agents

- All prices in USDC (6 decimals)
- Payment verification may take 5-30 seconds
- Keep transaction hashes for records
- Failed payments won't be retried automatically
- Build reputation for better rate limits
- Use exact amounts (no overpayment)
- Transactions are on-chain and immutable

## Testing

For testing, use the cheapest API first:
- JokeAPI: $0.0001 per request
- ExchangeRate: $0.0005 per request

## Common Errors

- 402: Payment required or invalid
- 403: Wallet blacklisted
- 429: Rate limit exceeded
- 500: Gateway error (check /health)

## Pricing Summary

| API | Price per Request | Authentication |
|-----|------------------|----------------|
| JokeAPI | $0.0001 | None |
| ExchangeRate | $0.0005 | None |
| Open-Meteo | $0.0005 | None |
| REST Countries | $0.0005 | None |
| CoinGecko | $0.001 | None |
| IP-API | $0.001 | None |
| OpenWeather | $0.002 | Your API Key |
| GitHub | $0.003 | Your Token |

Total cost for testing all 8 APIs: ~$0.008 USDC