# Agent AI Gateway (LLM)

Plain-text integration guide for the Agent AI Gateway. For the full walkthrough, see https://agentaigateway.com/docs.

## Base URL
https://api.agentaigateway.com/v1

## Prerequisites

This gateway is focused on Moltbot/OpenClaw agents using the xclaw02 skill.

### Install xclaw02
  npx xclaw02 openclaw init
  # or
  pip install xclaw02
  xclaw02 openclaw init

### xclaw02 CLI Commands
  xclaw02 probe <url>              # Check if URL requires payment
  xclaw02 pay <url> --max-amount 20  # Pay for resource
  xclaw02 wallet balance <addr>     # Check USDC balance

### References
- xclaw02 Skill: https://www.clawhub.ai/primer-dev/xclaw02
- xclaw02 npm: https://www.npmjs.com/package/xclaw02
- xclaw02 PyPI: https://pypi.org/project/xclaw02/
- xclaw02 GitHub: https://github.com/primer-systems/xClaw02

## Auth and Billing
- Send X-Wallet-Address on inference requests
- If balance is insufficient, POST /v1/deposit returns 402 with Payment-Required header
- xclaw02 handles payment signing automatically, or sign manually and retry with X-Payment
- Min deposit: 20 USDC on Base (eip155:8453)

## Step-by-step Flow
1) List models: GET /v1/models
2) Check balance: GET /v1/balance/:wallet
3) Deposit if needed: POST /v1/deposit (x402 402 flow, or use: xclaw02 pay <url> --max-amount 20)
4) Get auth challenge: POST /v1/auth/challenge with X-Wallet-Address
5) Chat completions: POST /v1/chat/completions with X-Wallet-Address, X-Auth-Payload, X-Auth-Signature
6) Optional streaming: add "stream": true

## Endpoints
- GET /v1/models - List models and pricing
- GET /v1/balance/:wallet - Wallet balance
- POST /v1/deposit - x402 deposit funding
- POST /v1/chat/completions - OpenAI-compatible inference

## Response Headers
- X-Credits-Remaining: remaining USD balance
- X-Credits-Used: cost of last request
- X-Low-Balance: "true" when below threshold
- Payment-Required: x402 payment requirements on 402 (V2 spec)
- X-Payment-Required: x402 payment requirements on 402 (legacy, also sent for compatibility)

## Examples

### 1) List models
Example:
  curl -s https://api.agentaigateway.com/v1/models

### 2) Check balance
Example:
  curl -s https://api.agentaigateway.com/v1/balance/0xYourWalletAddress

### 3) Deposit via x402
Example (first call returns 402 with X-Payment-Required):
  curl -X POST https://api.agentaigateway.com/v1/deposit     -H "Content-Type: application/json"     -d '{"amount_usdc": 20}'

Example (retry with X-Payment):
  curl -X POST https://api.agentaigateway.com/v1/deposit     -H "Content-Type: application/json"     -H "X-Payment: <base64-signed-payment>"     -d '{"amount_usdc": 20}'

### 4) Get auth challenge
Example:
  curl -s https://api.agentaigateway.com/v1/auth/challenge     -H "X-Wallet-Address: 0xYourWalletAddress"

### 5) Chat completions
Example (sign the challenge typed data and include in headers):
  curl -s https://api.agentaigateway.com/v1/chat/completions     -H "Content-Type: application/json"     -H "X-Wallet-Address: 0xYourWalletAddress"     -H "X-Auth-Payload: <base64-auth-payload>"     -H "X-Auth-Signature: <0x-signature>"     -d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"Hello"}]}'

### 6) Streaming (SSE)
Example:
  curl -N https://api.agentaigateway.com/v1/chat/completions     -H "Content-Type: application/json"     -H "X-Wallet-Address: 0xYourWalletAddress"     -H "X-Auth-Payload: <base64-auth-payload>"     -H "X-Auth-Signature: <0x-signature>"     -d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"Hello"}],"stream":true}'

## Skills
- https://agentaigateway.com/skill.md
- https://www.clawhub.ai/primer-dev/xclaw02