# Simbotica — LLM / AI Agent Integration Guide

## What is Simbotica?
Simbotica sells KYC-free physical SIM cards (data + voice + SMS) for humans and AI agents.
Price: $0.10 USDC per SIM card. Maximum 3 per order.

## Payment Protocol
This API uses the x402 HTTP payment protocol (ERC-3009 EIP-712 signed USDC authorization).
No API key, no account, no KYC required.

## Endpoints

### POST /api/submit-order-base
Network: Base Mainnet (eip155:8453)
Price: $0.10 USDC per unit
Facilitator: https://facilitator.xpay.sh
USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

### POST /api/submit-order-ethereum
Network: Ethereum Mainnet (eip155:1)
Price: $0.10 USDC per unit
Facilitator: https://facilitator.primev.xyz
USDC contract: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

## x402 Flow
1. Send POST with body (no payment header) → server returns HTTP 402 with JSON body containing payment requirements
2. Read `accepts` array from response body, pick your network
3. Sign EIP-3009 TransferWithAuthorization typed data with your EVM wallet
4. Retry POST with X-PAYMENT header (base64-encoded JSON payload) → server returns 200 with orderRef

## Request Body (JSON)
```json
{
  "quantity": 1,        // integer, 1–3
  "email": "agent@example.com",  // string, valid email — order confirmation sent here
  "payment": "usdc_x402"         // string, always "usdc_x402"
}
```

## Success Response (200)
```json
{
  "success": true,
  "orderRef": "SIM-1234567890",
  "txHash": "0x..."
}
```

## Error Responses
- 400: Missing/invalid fields
- 402: Payment required (body contains x402 payment terms)
- 500: Server error

## X-PAYMENT Header Format (base64-encoded JSON)
```json
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "resource": {
    "url": "https://simbotica.xyz/api/submit-order-base",
    "description": "Simbotica KYC-free SIM card order",
    "mimeType": "application/json"
  },
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xYOUR_ADDRESS",
      "to": "0xSIMBOTICA_WALLET",
      "value": "100000",
      "validAfter": "0",
      "validBefore": "1234567890",
      "nonce": "0xRANDOM_32_BYTES"
    }
  }
}
```

## OpenAPI spec: /openapi.json
## Agent manifest: /.well-known/agent.json