# Telenumerus — AI Agent Integration Guide

> SMS verification API. Get phone numbers and verification codes for 33 platforms. Self-service. Fully automated.

## Quick Start (3 steps)

### 1. Register (no human needed)
```
POST /api/v1/register
Body: {}
→ { "api_key": "your-key", "webhook_secret": "...", "next_steps": { "deposit": "GET /api/v1/deposit/addresses", "browse_services": "GET /api/v1/services", ... } }
```

### 2. Fund your account
```
GET /api/v1/deposit/addresses
→ { "addresses": { "btc": "bc1q...", "ltc": "ltc1q...", "usdt_erc20": "0x..." }, "minimum_deposit_usd": 1.00 }

POST /api/v1/deposit/verify
Headers: Authorization: Bearer <api_key>
Body: { "tx_hash": "64-char-hex-hash" }
→ { "status": "pending", "transaction_id": "...", "message": "Verifying on-chain..." }
```

### 3. Get a verified number + code

**Fastest: One-shot verify (order + wait + code in ONE call)**
```
POST /api/v1/verify
Headers: Authorization: Bearer <api_key>
Body: { "platform": "google", "country": "US", "timeout_seconds": 120 }
→ { "status": "ok", "phone": "+12025551234", "code": "847291", "delivery_seconds": 8, "price": 0.50 }
```

**Standard: Order then poll**
```
POST /api/v1/order
Headers: Authorization: Bearer <api_key>
Body: { "platform": "google", "country": "US" }
→ { "status": "ok", "order_id": "abc", "phone": "+12025551234", "price": 0.50, "expires_in": 300, "check_status": "/api/v1/order/abc", "stream": "/api/v1/order/abc/stream" }

GET /api/v1/order/abc
Headers: Authorization: Bearer <api_key>
→ { "status": "completed", "code": "847291" }
```
Note: Orders expire in 300 seconds. Poll every 5-10 seconds.

**Real-time: SSE stream (zero polling)**
```
GET /api/v1/order/abc/stream
Headers: Authorization: Bearer <api_key>
→ Server-Sent Events: { "event": "code", "code": "847291" }
```

**Natural language**
```
POST /api/v1/agent
Headers: Authorization: Bearer <api_key>
Body: { "query": "I need a Google verification number for UK" }
→ { "understood": true, "order_id": "abc", "phone": "+44...", "price": 0.50, "check_status": "/api/v1/order/abc" }
```
Returns 422 with `understood: false` if platform cannot be parsed.

**Batch (up to 20)**
```
POST /api/v1/batch
Headers: Authorization: Bearer <api_key>
Body: { "orders": [{"platform":"google"},{"platform":"discord","country":"UK"}] }
```

### 4. Cancel if needed
```
POST /api/v1/order/abc/cancel
Headers: Authorization: Bearer <api_key>
→ { "status": "ok", "refunded": 0.25 }
```

## Authentication (2 methods — pick either)
1. `Authorization: Bearer <api_key>` (recommended)
2. `X-API-Key: <api_key>` header

Note: API keys are NOT accepted in query strings (they leak into logs).

## Check Platform Availability Before Ordering
```
GET /api/v1/availability?country=US
→ { "platforms": [{ "platform": "google", "success_rate": 0.92, "stock": "high", "avg_delivery_seconds": 8, "price": 0.50, "hints": { "code_format": "numeric", "expect_code_length": 6 } }, ...] }
```
Note: `success_rate` can be `null` when insufficient data (fewer than 5 recent orders).

## Smart Features
- **Auto-retry**: If a number fails, the system automatically retries from a different source. No action needed.
- **Code extraction**: Raw SMS text is parsed — you get clean numeric codes (e.g., "847291" not "Your Google code is 847291").
- **Idempotency keys**: Add `"idempotency_key": "unique-string"` to /order or /verify for safe retries. Same key = same result, no double-charge.
- **Structured errors**: Every error includes `error_code` (machine-readable), `retryable` (boolean), `retry_after_seconds`.
- **Platform hints**: Order responses include `platform_hints` with expected code format and delivery time.

## Webhook Push Delivery (zero polling)
```
PUT /api/v1/webhook
Headers: Authorization: Bearer <api_key>
Body: { "url": "https://your-server.com/hook" }
```
Events: `sms.received`, `order.failed`, `balance.low`
Signature: HMAC-SHA256(body, webhook_secret) in X-Webhook-Signature header.
Retries: 5 attempts with exponential backoff (5s, 30s, 2min, 10min, 1hr).

## Error Codes
| Code | Retryable | Meaning |
|------|-----------|---------|
| RATE_LIMITED | yes | Too many requests. Wait retry_after_seconds. |
| INVALID_API_KEY | no | Bad API key |
| ACCOUNT_SUSPENDED | no | Account banned |
| INSUFFICIENT_BALANCE | no | Need more funds |
| UNKNOWN_PLATFORM | no | Platform not supported |
| ORDER_IN_PROGRESS | yes | Wait for current order |
| PROVIDER_UNAVAILABLE | yes | Temporarily unavailable — retry in 30s |
| ORDER_NOT_FOUND | no | Invalid order ID |
| INVALID_REQUEST | no | Missing or invalid parameters |
| INTERNAL_ERROR | yes | Server error — retry in a few seconds |

## Rate Limits
- 30 requests/minute per IP address
- 120 requests/minute per API key
- 1 concurrent order per account (next order after current completes/cancels)

## All Endpoints
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | /register | no | Create account |
| GET | /services | no | List platforms + prices |
| GET | /availability | no | Success rates + stock |
| GET | /health | no | Service status |
| GET | /deposit/addresses | no | Crypto deposit addresses |
| POST | /deposit/verify | yes | Submit TX hash for verification |
| POST | /order | yes | Get a phone number |
| POST | /verify | yes | Order + wait + return code |
| POST | /agent | yes | Natural language order |
| POST | /batch | yes | Up to 20 orders |
| GET | /order/:id | yes | Check order status |
| GET | /order/:id/stream | yes | SSE real-time stream |
| POST | /order/:id/cancel | yes | Cancel + refund |
| GET | /account | yes | Balance, tier, stats |
| GET | /usage | yes | Analytics |
| PUT | /webhook | yes | Set push notifications |

All paths are prefixed with `/api/v1/`.

## Supported Platforms (33)
Google, WhatsApp, Instagram, Telegram, Facebook, Twitter/X, Discord, TikTok, Snapchat, Uber, Amazon, Microsoft, Yahoo, LinkedIn, PayPal, Coinbase, Binance, OpenAI, Netflix, Spotify, Tinder, Steam, Viber, WeChat, Line, Reddit, Airbnb, eBay, Lyft, Nike, ProtonMail, Revolut, Wise

## Supported Countries (24)
US, RU, UA, GB, DE, FR, IN, ID, PH, BR, CA, NL, PL, ES, IT, SE, MX, AU, KR, JP, CN, TH, VN, MY

Default country is US if not specified.

## Loyalty Tiers (automatic)
| Tier | Orders | Discount |
|------|--------|----------|
| Standard | 0-19 | 0% |
| Silver | 20-49 | 5% |
| Gold | 50-99 | 10% |
| VIP | 100+ | 15% |

## MCP Tool Integration
For Claude/GPT native tool use, connect via MCP: `node mcp/server.js`
Tools: sms_register, sms_order, sms_verify, sms_check_order, sms_cancel_order, sms_account, sms_availability, sms_agent_order, sms_list_services

## OpenAPI Spec
Full machine-readable spec: GET /openapi.json