# SMSFAST activation API notes

Use this when a registration flow hard-requires SMS verification and the user provides a SMSFAST account/API key.

## API base

```text
https://backend.smsfast.io/stubs/handler_api.php
```

**CRITICAL**: The correct API host is `backend.smsfast.io`, NOT `api.smsfast.com`. `api.smsfast.com` returns `BAD_KEY` for valid keys. Discovered 2026-07-08 by inspecting the Nuxt `window.__NUXT__` config on the SMSFast homepage — `baseURL: "https://backend.smsfast.io/"` and `hostName: "backend.smsfast.io"` revealed the real backend.

The public site/domain (`https://smsfast.io`) is the Nuxt SPA frontend. The handler API lives on `backend.smsfast.io`, which is the same host that serves the Nuxt app's backend (`/api/auth`, `/api/user`, etc.).

## Core actions

```text
# Balance
GET /stubs/handler_api.php?api_key=[REDACTED]

# Buy activation number
GET /stubs/handler_api.php?api_key=[REDACTED]
# Optional: &operator=OPERATOR&maxPrice=PRICE
# Success: ACCESS_NUMBER:ID:NUMBER

# Poll SMS/status
GET /stubs/handler_api.php?api_key=[REDACTED]

# Get prices for a service (returns JSON: {COUNTRY: {SERVICE: {cost, count}}})
GET /stubs/handler_api.php?api_key=[REDACTED]

# Request resend
GET /stubs/handler_api.php?api_key=[REDACTED]

# Mark complete
GET /stubs/handler_api.php?api_key=[REDACTED]

# Cancel/refund
GET /stubs/handler_api.php?api_key=[REDACTED]
```

## Common responses

```text
BAD_KEY       invalid/expired API key, wrong account region, or key copied incorrectly
BAD_ACTION    wrong action name or malformed query
NO_BALANCE    account funds insufficient
NO_NUMBERS    no numbers for requested service/country/operator/maxPrice
NO_ACTIVATION activation ID not found
ACCESS_NUMBER:ID:NUMBER  number purchased successfully
```

## Website fallback / discovery pattern

If the API key returns `BAD_KEY`, do not keep retrying the same key. Use the website only to discover availability/prices, then ask for a working login/API key.

Observed UI flow:
1. Open `https://smsfast.io`.
2. Click **Купить номер**.
3. Search service name, e.g. `Twitter`.
4. Select service and country.
5. The final **Купить PRICE** button appears only after both are selected.
6. If not logged in, clicking buy opens the registration/login modal; purchase cannot complete without an authenticated SMSFAST account.

For X/Twitter specifically, the UI listed service `Twitter`; USA numbers were available and selectable. Treat prices/counts as time-varying and verify live before buying.

**Twitter/X pricing (2026-07-08):** `getPrices&service=tw` returned only country 115 with 13,532 numbers at 95.95 RUB. No other countries had Twitter available. USA numbers for Twitter cost ~14.63 RUB but were blocked by X's anti-fraud when used for signup.

## Pitfalls

- **Do not confuse API key with login/session token.** A random-looking string from settings may still return `BAD_KEY`; verify with `getBalance` before attempting purchases.
- **Use `api_key` as the parameter name, and `backend.smsfast.io` as the API host.** `api.smsfast.com` is the WRONG host — it returns `BAD_KEY` for valid keys. Discovered by inspecting `window.__NUXT__.config.public.baseURL` in the SMSFast homepage source. `smsfast.io/stubs/...` is a 404 SPA page, not the activation API.
- **Do not burn time on email when target has a phone wall.** For X/Twitter, valid AnyMessage emails can still lead to mandatory SMS verification on low-trust browser/IP sessions; move to SMS activation or an existing account.
- **Cancel failed/unused activations.** If the target refuses the number or no SMS arrives within the service window, call `setStatus&status=8&id=ID` when refund rules allow it. Early cancel may be denied (`EARLY_CANCEL_DENIED`).

- **X/Twitter blocks virtual numbers — even paid ones.** USA SMSFast numbers (+1 509 area code) were rejected by X with "Нам не удалось отправить вам SMS." Free public numbers (temporarynumber.com) are also blocked. X's anti-fraud classifies VoIP/virtual prefixes aggressively. Budget for multiple attempts across different countries; expect ~50%+ failure rate. Country 115 (95.95 RUB, 13.5K numbers) may have better acceptance than USA.