> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Official Tirdad SDKs for Go, Python, and TypeScript: what they share, how to install them, and which to pick

The Tirdad SDKs are typed clients generated from the same OpenAPI document as the API reference, with hand-written additions where a language needs them (an async event batcher in Go, webhook helpers in every SDK). They cover every public endpoint, retry transient failures once you turn retries on, and map API errors to typed values you can branch on.

> [card] [Go](https://pkg.go.dev/github.com/tirdad-billing/go-sdk/v2)
>
> Go 1.25 or newer. Typed errors and an async event batcher.

> [card] [Python](https://pypi.org/project/tirdad-sdk/)
>
> Python 3.10 or newer. Sync and async clients.

> [card] [TypeScript](https://www.npmjs.com/package/@tirdad/sdk)
>
> Node.js 18+, Bun, Deno, and edge runtimes.

| SDK | Package | Requires | Source |
| - | - | - | - |
| Go | `github.com/tirdad-billing/go-sdk/v2` | Go 1.25+ | [tirdad-billing/go-sdk](https://github.com/tirdad-billing/go-sdk) |
| Python | `tirdad-sdk` on PyPI | Python 3.10+ | [tirdad-billing/python-sdk](https://github.com/tirdad-billing/python-sdk) |
| TypeScript | `@tirdad/sdk` on npm | Node.js 18+, Bun, Deno, modern browsers | [tirdad-billing/ts-sdk](https://github.com/tirdad-billing/ts-sdk) |

## Installing a Tirdad SDK

```bash Go theme={null}
go get github.com/tirdad-billing/go-sdk/v2
```

```bash Python theme={null}
pip install tirdad-sdk
```

```bash TypeScript theme={null}
npm i @tirdad/sdk
```

## Configuring the SDK client

Every SDK takes two values: an API key and a server URL. The key decides the environment. The URL must include `/v1` with no trailing slash.

| Setting | Environment variable | Default |
| - | - | - |
| API key | `TIRDAD_API_KEY` | none, required |
| Server URL | `TIRDAD_API_HOST` | `https://api.tirdad.ai/v1` |

```go Go theme={null}
client := tirdad.New(
	tirdad.WithServerURL(os.Getenv("TIRDAD_API_HOST")),
	tirdad.WithSecurity(os.Getenv("TIRDAD_API_KEY")),
)
```

```python Python theme={null}
from tirdad_sdk import Tirdad

client = Tirdad(
    server_url="https://api.tirdad.ai/v1",
    api_key_auth=os.environ["TIRDAD_API_KEY"],
)
```

```typescript TypeScript theme={null}
import { Tirdad } from "@tirdad/sdk";

const tirdad = new Tirdad({
  serverURL: process.env.TIRDAD_API_HOST ?? "https://api.tirdad.ai/v1",
  apiKeyAuth: process.env.TIRDAD_API_KEY,
});
```

## The same call in each SDK language

Create a customer, then record one usage event for it:

```go Go theme={null}
_, err := client.Customers.CreateCustomer(ctx, types.CreateCustomerRequest{
	ExternalID: "cust_123",
	Name:       "Acme",
})

_, err = client.Events.IngestEvent(ctx, types.IngestEventRequest{
	EventName:          "api_request",
	ExternalCustomerID: "cust_123",
	Properties:         map[string]string{"region": "us-east-1"},
})
```

```python Python theme={null}
client.customers.create_customer(external_id="cust_123", name="Acme")

client.events.ingest_event(
    event_name="api_request",
    external_customer_id="cust_123",
    properties={"region": "us-east-1"},
)
```

```typescript TypeScript theme={null}
await tirdad.customers.createCustomer({ externalId: "cust_123", name: "Acme" });

await tirdad.events.ingestEvent({
  eventName: "api_request",
  externalCustomerId: "cust_123",
  properties: { region: "us-east-1" },
});
```

## What every SDK gives you

* **Full coverage.** Customers, plans, prices, features, entitlements, subscriptions, events, invoices, payments, wallets, credit notes, and the rest of the API, as one service per resource on the client.
* **Retries.** Off by default. Pass a retry config to the client and it retries `429` and `5xx` responses with backoff. Event ingestion is safe to retry because `event_id` dedupes.
* **Typed errors.** A `404`, `400`, `409`, or `429` surfaces as a value you can inspect rather than a bare string.
* **Webhook models.** Typed payload models for every webhook event, so a handler can parse the body without hand-written structs. See [Webhooks](https://docs.tirdad.ai/docs/webhook/webhooks).
* **Field naming.** The API uses `snake_case`. Go and TypeScript expose idiomatic `PascalCase` and `camelCase` fields and convert on the wire. Python keeps `snake_case`.

## Keep SDK keys on the server

The SDKs authenticate with an API key that can read and write your whole environment. Use them from backend code only. For browser and mobile code, generate a customer-scoped [portal session](https://docs.tirdad.ai/docs/customers/customer-portal#generating-a-portal-session) or proxy through your backend. See Harden client-side access.

## SDK versioning and releases

SDK releases are listed in the [changelog](https://docs.tirdad.ai/docs/changelog.md) and on each package registry. The SDKs are regenerated when the API changes, so an endpoint added to the API may appear in the reference before it appears in an SDK. Until it does, call it directly with the HTTP client of your choice; the SDK's key and base URL work unchanged.

> [card] [Using the SDKs](https://docs.tirdad.ai/developers/sdks/usage.md)
>
> Every SDK task in Go, Python, and TypeScript on one page: events, idempotency, errors, retries, pagination, and webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.