Authentication

Authentication

x402 Payment Protocol

The Tator API uses the x402 protocol for authentication. Instead of API keys, you pay a small USDC fee ($0.20) with each request. This enables truly permissionless access — no registration, no approval, no rate limits.

---

How x402 Works

Step 1: Make a Request (Get 402)

Send your request without payment. You'll receive a 402 Payment Required response with payment instructions.

curl -X POST https://x402.quickintel.io/v1/tator/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "buy $10 ETH on base",
    "walletAddress": "0xYourWallet...",
    "provider": "your-agent-name"
  }'

Response (402):

{
  "error": "Payment required",
  "message": "This endpoint requires $0.20 USDC to access.",
  "paymentRequired": {
    "x402Version": 2,
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "maxAmountRequired": "200000",
        "payTo": "0x6a35dF48189eB83404d97b32dd3E91517ff4ceb9",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "extra": {
          "name": "USD Coin",
          "version": "2"
        }
      }
    ]
  }
}

Step 2: Sign Payment Authorization

Sign an EIP-712 TransferWithAuthorization message that authorizes the USDC transfer.

const authorization = {
  from: walletAddress,        // Your wallet
  to: paymentInfo.payTo,      // Tator's payment address
  value: paymentInfo.maxAmountRequired,  // 200000 ($0.20)
  validAfter: 0,
  validBefore: Math.floor(Date.now() / 1000) + 3600,  // 1 hour
  nonce: randomBytes32()
};

const signature = await wallet.signTypedData({
  domain: {
    name: "USD Coin",
    version: "2",
    chainId: 8453,
    verifyingContract: paymentInfo.asset
  },
  types: {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" }
    ]
  },
  primaryType: "TransferWithAuthorization",
  message: authorization
});

Step 3: Retry with Payment Header

Encode the payment payload as base64 and include it in the PAYMENT-SIGNATURE header.

const paymentPayload = {
  x402Version: 2,
  scheme: "exact",
  network: "eip155:8453",
  payload: {
    signature,
    authorization: {
      from: walletAddress,
      to: paymentInfo.payTo,
      value: "200000",
      validAfter: "0",
      validBefore: validBefore.toString(),
      nonce: nonce
    }
  }
};

const paymentHeader = btoa(JSON.stringify(paymentPayload));

const response = await fetch("https://x402.quickintel.io/v1/tator/prompt", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PAYMENT-SIGNATURE": paymentHeader
  },
  body: JSON.stringify({
    prompt: "buy $10 ETH on base",
    walletAddress: walletAddress,
    provider: "your-agent-name"
  })
});

Step 4: Payment Settled, Response Returned

The gateway verifies your signature, settles the USDC payment on-chain, and returns the API response.

The PAYMENT-RESPONSE header contains settlement details:

{
  "success": true,
  "txHash": "0x44da78c62707baa63cba7293d6bb49fb71927be0ff5bf24312b170120e75e689",
  "network": "eip155:8453",
  "blockNumber": 42152565
}

---

Important: Payment is Non-Refundable

You are charged per API call regardless of the outcome.

This means:

• ✅ Successful trade → Charged $0.20

• ✅ Price check (info query) → Charged $0.20

• ⚠️ Unclear prompt (asks for clarification) → Charged $0.20

• ⚠️ Invalid prompt (error response) → Charged $0.20

Tip: Validate your prompts before sending. Include chain, token, and amount to avoid wasted calls.

---

Payment Networks

You can pay from any of these networks. Choose the one with lowest fees or where you have USDC.

Network	Chain ID	CAIP-2	Token	Decimals
Base	8453	eip155:8453	USDC	6
Ethereum	1	eip155:1	USDC	6
Arbitrum	42161	eip155:42161	USDC	6
Optimism	10	eip155:10	USDC	6
Polygon	137	eip155:137	USDC	6
Avalanche	43114	eip155:43114	USDC	6
Unichain	130	eip155:130	USDC	6
Linea	59144	eip155:59144	USDC	6
MegaETH	4326	eip155:4326	USDM	18

Recommended: Use Base for lowest gas fees.

Note: MegaETH uses USDM with 18 decimals. The payment amount is scaled accordingly.

---

Discovery Endpoint

Query the /accepted endpoint to get current payment requirements:

curl https://x402.quickintel.io/accepted

Response:

{
  "x402Version": 2,
  "service": "quickintel-x402-gateway",
  "routes": [
    {
      "path": "/v1/tator/*",
      "backend": "Tator Trader",
      "price": "$0.20",
      "payTo": "0x6a35dF48189eB83404d97b32dd3E91517ff4ceb9",
      "requiredFields": {
        "prompt": "string (required)",
        "walletAddress": "string (required)",
        "provider": "string (required)"
      },
      "networks": [
        {
          "network": "eip155:8453",
          "chainId": 8453,
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "assetName": "USD Coin",
          "decimals": 6,
          "amountRequired": "200000"
        }
      ]
    }
  ]
}

---

Pricing

Service	Price	Atomic Units (6 decimals)
Tator API	$0.20	200000

---

EIP-712 Domain

For signing the payment authorization, use this EIP-712 domain:

// For USDC (most chains)
const domain = {
  name: "USD Coin",
  version: "2",
  chainId: chainId,  // e.g., 8453 for Base
  verifyingContract: usdcAddress
};

// For MegaETH (USDM)
const domain = {
  name: "MegaUSD",
  version: "1",
  chainId: 4326,
  verifyingContract: "0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7"
};

---

USDC Contract Addresses

Chain	USDC Address
Base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Ethereum	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Arbitrum	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Optimism	0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85
Polygon	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Avalanche	0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
Unichain	0x078D782b760474a361dDA0AF3839290b0EF57AD6
Linea	0x176211869cA2b568f2A7D4EE941E073a821EE1ff
MegaETH	0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7 (USDM)

---

Important Notes

Native USDC Only

Only native USDC is supported (implements EIP-3009). Bridged USDC.e will not work.

Payment Amount

• Tator: 200000 atomic units = $0.20 USDC (6 decimals)

• Quick Intel: 30000 atomic units = $0.03 USDC (6 decimals)

• MegaETH: Scaled for 18 decimals (e.g., 200000000000000000 for $0.20 USDM)

Validity Window

Set validBefore to at least 5 minutes in the future to allow time for processing. Recommended: 1 hour.

Nonce

Generate a unique random bytes32 nonce for each payment to prevent replay attacks.

---

Free Endpoints

These endpoints don't require payment:

Endpoint	Description
GET /health	Gateway health check
GET /accepted	Payment discovery
GET /v1/tator/health	Tator backend health
GET /v1/tator/jobs/:id	Poll job status (async mode)

---

Next Steps

• Endpoints — Full API reference

• Request & Response — Detailed format documentation

• Example Flows — Complete code examples