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
| Method | Description |
|---|
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
| Field | Type | Default | Description |
|---|
agentId | string | required | Agent identifier |
country | string | "US" | ISO country code: currently US |
serviceUrl | string | — | Infer country from URL if country omitted |
ttlSeconds | number | 3600 | Session lifetime (60–86400) |
webhookUrl | string | — | URL for OTP push delivery |
WaitForOtpOptions
| Field | Type | Default | Description |
|---|
timeout | number | 60 | Max seconds to wait |
Exception hierarchy
| Class | HTTP | When thrown |
|---|
AgentSimError | — | Base class |
AuthenticationError | 401 | Missing or invalid API key |
ForbiddenError | 403 | Insufficient permissions |
ValidationError | 422 | Invalid request parameters |
OtpTimeoutError | 408 | No parseable OTP within timeout. Inspect raw messages and support matrix before retrying. |
PoolExhaustedError | 503 | No numbers in requested country |
RateLimitError | 429 | Too many requests |
SessionNotFoundError | 404 | Session not found |
ApiError | varies | Unclassified 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.