Typed Dart client for the OnlineSim API — SMS numbers, rent, account and free numbers. Flutter, CLI, server and web.

Install

Dart 3.0 or newer, or any Flutter 3.10+ app. Pure Dart: the only dependency is package:http, so it runs on every platform, the web included.

dart pub add onlinesim

Quick start

Check the balance, order a number, wait for the SMS code.

import 'package:onlinesim/onlinesim.dart';

Future<void> main() async {
  final client = OnlineSim(apiKey: 'your-api-key');

  final balance = await client.user.balance();
  print('available: ${balance.available} USD');

  final order = await client.numbers.getWithNumber('google', country: 44);
  print('enter ${order.number} in the app');

  // Polls every 5 s for up to 10 min, then closes the operation.
  final code = await client.numbers.waitCode(order.tzid);
  print('code: $code');

  client.close();
}

Client options

import 'package:onlinesim/onlinesim.dart';

final client = OnlineSim(
  apiKey: 'your-api-key',
  lang: 'en',
  timeout: const Duration(seconds: 15),
);
OptionTypeDefaultDescription
apiKeyString?—Sent as Authorization: Bearer <apiKey>, never in the URL. Not needed for tariffs and free numbers.
baseUrlStringhttps://onlinesim.host/api/API base; trailing slash optional.
langString'en'Language of server texts (lang query parameter).
devIdString?—Partner developer id (dev_id), sent only when set.
timeoutDuration30 sPer-request timeout.
transportOnlineSimTransport?HttpTransport()Transport: an HttpTransport over your own http.Client (proxy, custom TLS, retries), MockOnlineSim, or a fake in tests.

Sections: client.numbers, client.rent, client.user, client.free. Webhook bodies are parsed by the top-level parseWebhook.

client.close() closes the default http.Client. A transport you pass in stays open: close it yourself.

import 'package:http/http.dart' as http;
import 'package:onlinesim/onlinesim.dart';

final http.Client httpClient = http.Client();
final client = OnlineSim(apiKey: 'your-api-key', transport: HttpTransport(httpClient));

Results are typed classes with camelCase fields (guard_interval_remaining_seconds → guardIntervalRemainingSeconds). Money the server sends as a decimal string (balance, rent sum in rent.state) is a double, maps that arrive as an empty PHP array [] are {}, and maps keyed by country code or rent days have int keys. paymentHistory().paylist that arrives as a JSON array (ids 0, 1, 2…) is kept as a map keyed '0', '1', …

Error handling

Every exception extends the sealed OnlineSimException (message).

ClassWhenFields
ApiExceptionThe API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER).code, message
NoNumberExceptionNO_NUMBER: no number right now. Subclass of ApiException.code, message
TransportExceptionNetwork error, request timeout, or a body that is not JSON.status (null without a response), body (first 500 chars)
WaitTimeoutExceptionwaitCode got no code within its timeout.—
WebhookFormatExceptionparseWebhook got something that is not a JSON object.—
import 'package:onlinesim/onlinesim.dart';

Future<void> order(OnlineSim client) async {
  try {
    await client.numbers.get('google', country: 44);
  } on NoNumberException {
    // try another country or later
  } on ApiException catch (e) {
    print('${e.code}: ${e.message}'); // e.g. WARNING_LOW_BALANCE
  } on TransportException catch (e) {
    print('network ${e.status} ${e.body}');
  }
}

message is the server's text when it sends one, otherwise a short English description of the code (errorMessages), otherwise the code itself. Profile validation failures become ApiException with code VALIDATION_ERROR.