Skip to main content

Installation

bun add @agentsim/sdk
# or: npm install @agentsim/sdk
Requires TypeScript 5.2+ for await using (automatic release). Works with Node.js 18+, Bun, Deno, and edge runtimes.

Authentication

Set the AGENTSIM_API_KEY environment variable:
export AGENTSIM_API_KEY="asm_live_..."
Or pass the key explicitly:
import { AgentSimClient } from "@agentsim/sdk";
const client = new AgentSimClient("asm_live_...");

Methods

MethodDescription
provision(options, client?)Provisions a number and returns a NumberSession
num.waitForOtp(options?)Waits for an OTP, returns OtpResult
num.release()Manually release the number
num[Symbol.asyncDispose]()Called automatically by await using
provision() starts a billable session after the free tier. $0.99 per session on the Builder plan. OtpTimeoutError means no parseable OTP arrived within the wait window; inspect raw messages and destination support before retrying.

Full example

import { provision, OtpTimeoutError, PoolExhaustedError } from "@agentsim/sdk";

async function getOtp() {
  try {
    // await using releases the number automatically when the block exits
    await using num = await provision({
      agentId: "stripe-onboarding",
      country: "US",
      ttlSeconds: 300,
    });

    console.log("Provisioned:", num.number);
    // Enter num.number into the service that will send the OTP...

    const otp = await num.waitForOtp({ timeout: 60 });
    console.log("OTP:", otp.otpCode);
    return otp.otpCode;

  } catch (err) {
    if (err instanceof OtpTimeoutError) {
      console.log("No OTP in 60s. Inspect raw messages and support matrix before retrying.");
    } else if (err instanceof PoolExhaustedError) {
      console.log("No US numbers available right now.");
    } else {
      throw err;
    }
  }
}

Manual release (TypeScript < 5.2)

If you can’t use await using, call release() manually:
import { provision } from "@agentsim/sdk";

const num = await provision({ agentId: "my-bot" });
try {
  const otp = await num.waitForOtp({ timeout: 60 });
  console.log(otp.otpCode);
} finally {
  await num.release();
}

ProvisionOptions

FieldTypeDefaultDescription
agentIdstringrequiredAgent identifier
countrystring"US"ISO country code: currently US
serviceUrlstringInfer country from URL if country omitted
ttlSecondsnumber3600Session lifetime (60–86400)
webhookUrlstringURL for OTP push delivery

WaitForOtpOptions

FieldTypeDefaultDescription
timeoutnumber60Max seconds to wait

Exception hierarchy

ClassHTTPWhen thrown
AgentSimErrorBase class
AuthenticationError401Missing or invalid API key
ForbiddenError403Insufficient permissions
ValidationError422Invalid request parameters
OtpTimeoutError408No parseable OTP within timeout. Inspect raw messages and support matrix before retrying.
PoolExhaustedError503No numbers in requested country
RateLimitError429Too many requests
SessionNotFoundError404Session not found
ApiErrorvariesUnclassified API error

Zero dependencies

The TypeScript SDK has no runtime dependencies. It uses the built-in fetch API. The only peer dependency is TypeScript itself.