Developer SDK

Verification-first inference. One client.

The @turnstileai/sdk is a TypeScript SDK for TurnstileAI a verification-first AI gateway that adds trustable receipts, provider visibility, and optional Solana-backed checkpoints to every completion.

Read the docs View on GitHub

Install

One package. Node, Bun, Deno.

Install the SDK and export your API key. Zero additional configuration the client connects to https://api.turnstileai.net/v1 by default.

TypeScriptESM + CJSEdge-readyMIT

terminal

bash

1npm install @turnstileai/sdk

.env

bash

1TURNSTILEAI_API_KEY=ts_live_...

Quickstart

Your first verified completion.

Initialize TurnstileAI, call client.chat(), and get back output, record, and verification in one response. Set anchor: "solana" to write the proof on-chain.

quickstart.ts

1import { TurnstileAI } from "@turnstileai/sdk";

3const client = new TurnstileAI({

4 apiKey: process.env.TURNSTILEAI_API_KEY!

5});

7const result = await client.chat({

8 model: "openrouter/llama-3.1-70b",

9 messages: [

10 { role: "user", content: "Explain zero-knowledge rollups simply." }

11 ],

12 receipt: true,

13 anchor: "solana",

14 routeMode: "trust-first"

15});

17console.log(result.output);

18console.log(JSON.stringify(result.record, null, 2));

19console.log(JSON.stringify(result.verification, null, 2));

Config parameters

Client initialisation options.

apiKeystring

Your TurnstileAI API key.

baseURLstring

API base URL. Defaults to https://api.turnstileai.net/v1.

timeoutnumber

Request timeout in milliseconds.

defaultRouteModeRouteMode

Optional default routing strategy applied to every request.

defaultLedgerModeLedgerMode

Optional default ledger/checkpoint mode.

Chat options

Per-request controls.

modelrequired

Model routing path e.g. "openai/gpt-4o-mini" or "openrouter/llama-3.1-70b".

messagesrequired

Message array with role and content.

receipttrue

Include a verification-oriented run record in the response.

anchor"off-chain"

Checkpoint mode: "solana", "off-chain", or "none".

routeMode"trust-first"

Routing strategy for provider selection.

provider

Pin inference to a specific provider.

maxSpendUsd

Maximum spend cap for a single request.

temperature

Sampling temperature.

maxTokens

Output token limit.

Beyond chat

Records, providers, usage, and CLI.

// record APIs

records.ts

1// Fetch a run record by ID

2const record = await client.records.get("rr_123");

4// Re-verify a record's signature and anchor

5const verification = await client.records.verify("rr_123");

7// List available providers

8const providers = await client.providers.list();

10// Pull usage stats for the current month

11const usage = await client.usage.overview("month");

// CLI

terminal

bash

1# Authenticate

2turnstileai auth check --key=ts_live_xxx

4# Records

5turnstileai record get rr_123 --key=ts_live_xxx

6turnstileai record list --key=ts_live_xxx

7turnstileai record verify rr_123 --key=ts_live_xxx

9# Providers & usage

10turnstileai providers list --key=ts_live_xxx

11turnstileai usage overview --key=ts_live_xxx

Local testing

Sandboxed mock mode no network needed.

Use an API key starting with ts_test_, or set TURNSTILEAI_MOCK=true, and the SDK falls back to local mock mode. Iterate offline and write integration tests without hitting the live gateway.

terminal

bash

1# Use a test key prefix SDK falls back to local mock mode

2TURNSTILEAI_API_KEY=ts_test_yourkey npm run dev

4# Or set the env flag explicitly

5TURNSTILEAI_MOCK=true npm run dev

API surface

A small, predictable method set.

client.chat(options)

Run a verified inference completion. Returns output, record, and verification.

client.records.get(id)

Fetch a run record by ID.

client.records.verify(id)

Re-check a record's signature and Solana anchor.

client.providers.list()

List all available inference providers and their current status.

client.usage.overview(period)

Pull spend, token, and latency rollups. Pass "month", "week", or "day".

Ship your first verified completion in minutes.

Get an API keySBrowse the docs