# SMS Receive API Verification (mytempsms.com / receivesms.top)

## Pattern: API on different domain than website

The public API for mytempsms.com is at `america.receivesms.top`, NOT at `mytempsms.com`. The website has no API endpoints — it's a web UI behind Cloudflare. The API docs are at `https://mytempsms.com/api-docs/v5.html`.

**Always check for API docs pages** (`/api-docs/`, `/docs`, `/api`) before concluding a service has no API.

## Auth format: `SecretKey`, not `Bearer`

```
Authorization: SecretKey D2B25249546AC0FE146AA3F819DDE3E8
```

NOT `Bearer <key>`. The key format is a 32-char hex string (MD5-like).

## Base URL and endpoints

- **Base:** `https://america.receivesms.top/api/v5/`
- **Auth:** `SecretKey <key>` header
- **All endpoints are POST** with JSON body (`Content-Type: application/json`)

### Key endpoints

| Endpoint | Purpose | Body |
|---|---|---|
| `POST /api/v5/get_user` | Balance check | `{}` |
| `POST /api/v5/get_project` | List projects (services) | `{}` |
| `POST /api/v5/get_country` | List countries | `{}` |
| `POST /api/v5/get_price` | Price for project+country | `{"project_id": N}` |
| `POST /api/v5/get_phone` | Get phone number | `{"project_id": N, "country_id": N}` |
| `POST /api/v5/get_message` | Get SMS for order | `{"order_id": "..."}` |
| `POST /api/v5/cancel_order` | Cancel order | `{"order_id": "..."}` |

## Balance check

```bash
curl -s -X POST "https://america.receivesms.top/api/v5/get_user" \
  -H "Content-Type: application/json" \
  -H "Authorization: SecretKey <KEY>" \
  -d '{}'
```

Response: `{"error_code":0,"msg":"Request successful","data":{"tokens":0}}`

- `error_code: 0` = auth OK, key is valid
- `tokens: 0` = no balance

## Pitfall: 0 tokens = "high usage" error, not "insufficient balance"

When trying `get_phone` with 0 tokens, the API returns:

```json
{"error_code":4000,"msg":"Due to high current usage, we recommend trying multiple times..."}
```

This is MISLEADING. It's not actually high usage — it's zero balance. The API does not have an explicit "insufficient tokens" error for `get_phone`. When you see this error across multiple countries consistently, especially with `error_code: 4000`, it means no balance.

**Do not waste time retrying different countries — check tokens first with `get_user`.**

## Free tier

The web version at `mytempsms.com` has free public numbers (SMS visible to everyone), but the site is behind Cloudflare anti-bot protection. The API has no free tier — requires token balance > 0.

## Quick verification script

```bash
#!/bin/bash
KEY="$1"
BASE="https://america.receivesms.top/api/v5"

# Check balance
echo "=== Balance ==="
curl -s -X POST "$BASE/get_user" \
  -H "Content-Type: application/json" \
  -H "Authorization: SecretKey $KEY" \
  -d '{}' | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'tokens={d[\"data\"][\"tokens\"]}')"

# Try getting a phone (will fail if tokens=0)
echo "=== Get Phone (US, Telegram) ==="
curl -s -X POST "$BASE/get_phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: SecretKey $KEY" \
  -d '{"project_id":1,"country_id":226}' | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('msg','')[:120])"
```