# Luban SMS provider integration notes — 2026-05-11

Source docs: https://lubansms.com/api_docs/

## API shape

All endpoints are GET under:

```text
https://lubansms.com/v2/api
```

Every request uses `apikey=<secret>` query parameter. Do not log it.

Important quirk found during integration: plain Python urllib requests without a browser-like User-Agent returned HTTP 403. Adding a Chrome-like UA made both `https` and `http` balance requests return HTTP 200.

## Core endpoints

```text
GET /getBalance?apikey=...
GET /countries?apikey=...
GET /List?apikey=...&country=<countryName>&service=<serviceName>&language=en&page=1
GET /getNumber?apikey=...&service_id=<service_id>
GET /getSms?apikey=...&request_id=<request_id>
GET /setStatus?apikey=...&request_id=<request_id>&status=reject
GET /getAgainNmuber?apikey=...&request_id=<request_id>
GET /smsHistory?apikey=...&language=en&page=1
```

## Response mapping

Buy success:

```json
{"code":0,"msg":"","number":"79781901206","request_id":230698}
```

Poll waiting:

```json
{"code":0,"msg":"wait","sms_msg":{"request_id":"244936588","application_id":133,"country_id":1,"number":"79587588703"}}
```

Poll success:

```json
{"code":0,"msg":"success","sms_code":"380682"}
```

Cancel/release:

```json
{"code":0,"msg":"success"}
```

## Verified with BOSS key

Do not disclose the key. It was stored in `~/.hermes/env/codex_oauth_onboarding.env` as `LUBAN_SMS_API_KEY`.

Verification output after adding Chrome UA:

```json
{"http":200,"code":0,"ok":true,"balance":"2.000","msg":""}
```

OpenAI service search returned usable entries, including:

```json
{"service_id":"537935","country_en":"United Kingdom/England","country_zh":"英国/英格兰","service_name":"OpenAI","provider":"acsim","cost":0.05}
```

## Local helper

```bash
/Users/chick/homebrew/opt/python@3.11/bin/python3.11 \
  /Users/chick/.hermes/skills/software-development/codex-oauth-plus-onboarding/scripts/luban_sms.py balance

/Users/chick/homebrew/opt/python@3.11/bin/python3.11 \
  /Users/chick/.hermes/skills/software-development/codex-oauth-plus-onboarding/scripts/luban_sms.py services --service OpenAI --language en --limit 20

/Users/chick/homebrew/opt/python@3.11/bin/python3.11 \
  /Users/chick/.hermes/skills/software-development/codex-oauth-plus-onboarding/scripts/luban_sms.py resolve --service OpenAI --language en --pages 5
```

## Runner integration

`phone_verify_until_success.py` now supports:

```bash
PHONE_SMS_PROVIDER=luban
```

Provider abstraction:

```text
sms_buy(country)    -> Luban getNumber(service_id resolved from /List)
sms_check(id)       -> Luban getSms(request_id)
sms_cancel(id)      -> Luban setStatus(... status=reject)
sms_finish(id)      -> no-op success for Luban
```

Country names map from the existing 5sim country slugs to Luban English country names when available.