Docs · SDKs

Use the SDKs

TypeScript and Python clients for the same calls as the REST API, plus packages for three agent frameworks.

Make your first call

Install
```
npm install straleio
```
```
pip install straleio
```
The TypeScript client needs Node.js 18 or later. The Python client needs Python 3.9 or later.
Get a key

The SDKs send your API key with every call, so they need one even for free tools. Sign up, then set STRALE_API_KEY in your environment. Free tools cost nothing with a key, and keyless free calls are limited to 300 a month per IP address. To call without a key, use the REST API.

Call a free tool

This runs IBAN Validation. max_price_cents is required and caps the price of the call.

import { Strale } from "straleio";

const strale = new Strale({ apiKey: process.env.STRALE_API_KEY! });
const result = await strale.do({
  capability_slug: "iban-validate",
  inputs: {
    "iban": "SE4550000000058398257466"
  },
  max_price_cents: 5,
});
console.log(result.output);

import os
from straleio import Strale, DoRequest

strale = Strale(api_key=os.environ["STRALE_API_KEY"])
result = strale.do(DoRequest(
    capability_slug="iban-validate",
    inputs={
        "iban": "SE4550000000058398257466",
    },
    max_price_cents=5,
))
print(result.output)

Read the result

result has the response fields at the top level: output, price_cents, latency_ms, provenance, transaction_id and wallet_balance_cents. result.meta holds the audit record. If a tool runs in the background, the SDK polls until it finishes.

Client options

TypeScript	Python	Default	Meaning
`apiKey`	`api_key`	required	Your API key.
`baseUrl`	`base_url`	`https://api.strale.io`	The API to call.
`defaultMaxPriceCents`	`default_max_price_cents`	none	The price ceiling used when a call sets none.
`timeout`	`timeout`	60 s	How long to wait for each request. TypeScript takes milliseconds, Python seconds.
`pollInterval`	`poll_interval`	2 s	How often to check a background call.
`maxPollWait`	`max_poll_wait`	120 s	How long to wait for a background call before raising `timeout_exceeded`.

Handle errors

A failed call raises StraleError. It carries the API’s error_code, the HTTP status and details. Common codes have their own subclass: InsufficientBalanceError, NoMatchingCapabilityError, CapabilityUnavailableError, ExecutionFailedError, TimeoutExceededError, InvalidRequestError, RateLimitedError, UnauthorizedError and NotFoundError. Which to retry is in Handle errors and retries.

import { Strale, StraleError, InsufficientBalanceError } from "straleio";

const strale = new Strale({ apiKey: process.env.STRALE_API_KEY! });

try {
  const result = await strale.do({ capability_slug: "iban-validate", inputs: {"iban":"SE4550000000058398257466"}, max_price_cents: 1 });
} catch (err) {
  if (err instanceof InsufficientBalanceError) {
    console.log(err.walletBalanceCents, err.requiredCents); // top up, then retry
  } else if (err instanceof StraleError) {
    console.log(err.errorCode, err.statusCode, err.message, err.details);
  } else {
    throw err;
  }
}

import os
from straleio import Strale, DoRequest, InsufficientBalanceError, StraleError

strale = Strale(api_key=os.environ["STRALE_API_KEY"])

try:
    result = strale.do(DoRequest(capability_slug="iban-validate", inputs={ "iban": "SE4550000000058398257466", }, max_price_cents=1))
except InsufficientBalanceError as err:
    print(err.wallet_balance_cents, err.required_cents)  # top up, then retry
except StraleError as err:
    print(err.error_code, err.status_code, str(err), err.details)

Retries, balance, history

Pass idempotency_key to make a retry safe. The clients also read your balance, fetch a past call by transaction ID and list the catalogue.

import { randomUUID } from "node:crypto";

// Retry-safe call: the same key returns the first result instead of running twice.
const result = await strale.do({
  capability_slug: "iban-validate",
  inputs: {"iban":"SE4550000000058398257466"},
  max_price_cents: 1,
  idempotency_key: randomUUID(),
});

const balance = await strale.balance();                          // { balance_cents, currency }
const record = await strale.transaction(result.transaction_id);  // a past call
const recent = await strale.transactions();                      // your latest calls
const tools = await strale.capabilities();                       // the catalogue

import uuid

# Retry-safe call: the same key returns the first result instead of running twice.
result = strale.do(DoRequest(
    capability_slug="iban-validate",
    inputs={ "iban": "SE4550000000058398257466", },
    max_price_cents=1,
    idempotency_key=str(uuid.uuid4()),
))

balance = strale.balance()                          # balance_cents, currency
record = strale.transaction(result.transaction_id)  # a past call
recent = strale.transactions()                      # your latest calls
tools = strale.capabilities()                       # the catalogue

Spend limits and how idempotency works are in Retry safely and cap spend.

Framework packages

Each package turns Strale’s tools into the tool type its framework already uses. Every package takes an API key.

LangChain

pip install langchain-strale

import os
from langchain_strale import StraleToolkit

toolkit = StraleToolkit(api_key=os.environ["STRALE_API_KEY"])
tools = toolkit.get_tools()  # pass categories=["finance"] to filter

Python 3.10 or later. Each Strale tool becomes a LangChain tool, plus search and balance tools.

CrewAI

pip install crewai-strale

import os
from crewai_strale import StraleToolkit

toolkit = StraleToolkit(api_key=os.environ["STRALE_API_KEY"])
tools = toolkit.get_tools()  # pass categories=["finance"] to filter

Python 3.10 or later. Pass the tools to an Agent with tools=tools.

Composio

pip install composio-strale

import os
from composio import Composio
from composio_strale import register_strale_tools

composio = Composio()
register_strale_tools(composio, api_key=os.environ["STRALE_API_KEY"])

Python 3.10 or later. Registers STRALE_SEARCH, STRALE_EXECUTE and STRALE_BALANCE under the strale toolkit.

Get an API key Back to Docs