API Reference

Base URL

Authentication

Include your API key in the Authorization header:

Execute Command

Execute a bot command with automatic HTTP 402 payment flow.

Endpoint

Headers

• Content-Type: application/json (required)
• Idempotency-Key: Unique request identifier (required)
• X-402-Nonce: Payment session nonce (after approval)

Request Body

{
  "args": {
    "q": "BTC"
  },
  "user_id": "tg:123"
}

Response (402 Payment Required)

First request returns 402 with pricing information:

HTTP/1.1 402 Payment Required
X-402-Price: 0.05
X-402-Currency: USDC
X-402-Chain: solana
X-402-Nonce: abc123...
X-402-Expires: 1699999999

{
  "error": "Payment Required",
  "message": "This command costs 0.05 USDC"
}

Response (200 Success)

After payment approval:

{
  "result": {
    "message": "Command executed successfully",
    "data": { ... }
  },
  "receipt": {
    "tx_ref": "5KJp8...",
    "amount": 0.05,
    "currency": "USDC",
    "chain": "solana",
    "command": "analyze",
    "user_id": "tg:123",
    "idempotency_key": "abc-123",
    "ts": "2025-11-05T10:00:00Z",
    "settlement_ms": 1850,
    "signature": "7f8a9b..."
  }
}

Example

curl -i -X POST https://x402tele.app/api/v1/bots/mybot/commands/analyze \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"args":{"q":"BTC"},"user_id":"tg:123"}'

Get Prices

Retrieve the price table for all commands.

Endpoint

Response

{
  "prices": [
    {
      "command": "analyze",
      "type": "per-call",
      "amount": 0.05,
      "currency": "USDC",
      "chain": "solana"
    },
    {
      "command": "search",
      "type": "per-unit",
      "amount": 0.01,
      "currency": "USDC",
      "chain": "solana",
      "unitLabel": "result"
    }
  ],
  "updated_at": "2025-11-05T10:00:00Z"
}

Issue Time-Pass Key

Generate a time-limited access key for unlimited command usage.

Endpoint

Request Body

{
  "command": "premium-daily",
  "user_id": "tg:123"
}

Response

{
  "key": "tp_abc123...",
  "command": "premium-daily",
  "issued_at": "2025-11-05T10:00:00Z",
  "expires_at": "2025-11-06T10:00:00Z",
  "duration_seconds": 86400
}

Error Codes