Luban SMS provider integration notes — 2026-05-11

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

API shape

All endpoints are GET under:

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

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:

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

Poll waiting:

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

Poll success:

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

Cancel/release:

{"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:

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

OpenAI service search returned usable entries, including:

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

Local helper

/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:

PHONE_SMS_PROVIDER=luban

Provider abstraction:

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.

2.8 KiB Raw Permalink Blame History