# SDKs

> Client libraries for TypeScript, Python and Rust, how to choose between them, and when to call the API directly instead.

Three client libraries cover the trading API. They are thin conveniences over the
same HTTP and WebSocket surface, so anything a library does you can also do with
a direct request. Pick a library to skip the wire details, or call the API
directly for full control over every byte you send.

<Cards>
<Card title="TypeScript" href="/docs/sdks/typescript">
Widest coverage, including market and event discovery. Integer micro amounts
only, so nothing is rounded on your behalf.
</Card>

<Card title="Python" href="/docs/sdks/python">
Fastest route to a working script. Takes dollars and shares and converts them
for you, with both sync and async clients.
</Card>

<Card title="Rust" href="/docs/sdks/rust">
Async client with exact decimal amounts, typed identifiers, and signing and
streaming behind cargo features.
</Card>

<Card title="Call the API directly" href="/docs/quickstart">
No dependency at all. The quickstart places an order with plain HTTP requests.
</Card>
</Cards>

<Callout type="warn" title="Install from source for now">
None of the three is on npm, PyPI or crates.io yet. Each page installs from the
public [`agara-sdks`](https://github.com/Mirai-Tech-Inc/agara-sdks) repository,
which works today. Once the packages are published the install step becomes one
ordinary command and the rest of each page is unchanged.
</Callout>

## Compare the libraries [#compare-the-libraries]

They are not interchangeable. They cover different parts of the API and take
amounts in different forms, so choose on the rows that matter to you rather than
on language preference alone.

|                            | TypeScript                                 | Python                                 | Rust                                 |
| -------------------------- | ------------------------------------------ | -------------------------------------- | ------------------------------------ |
| Package                    | `@agara/sdk`                               | `agara-sdk`                            | `agara-sdk`                          |
| Runtime                    | Node 22 or newer, ESM only                 | Python 3.10 or newer                   | async, on tokio                      |
| Amounts you pass           | integer micro units only                   | dollars and shares, converted for you  | exact decimals                       |
| Concurrency                | promise-based                              | sync, with an async client in an extra | async only                           |
| Trading and portfolio      | yes                                        | yes                                    | yes                                  |
| Market and event discovery | yes, with calendars, securities and search | no                                     | no                                   |
| LP rewards and rebates     | no                                         | no                                     | yes                                  |
| Order signing              | orders and account batches                 | orders                                 | orders, behind a feature             |
| Streaming                  | market, account and both price feeds       | market and account, in an extra        | market and account, behind a feature |
| Breadth                    | 38 documented operations                   | about 20 trading methods               | about 20 trading methods             |

Two rows deserve a note.

**Amounts** is the row most likely to surprise you. Python lets you write
`price=0.60`; TypeScript requires `price_micro: "600000"` and refuses a value
that would round. Neither is more correct, but the same mistake is converted in
one and rejected in the other. [Conventions](/docs/conventions) has what the wire
format actually requires.

**Breadth** is about surface, not quality. TypeScript wraps every documented
operation including discovery, so it can carry a whole integration. Python and
Rust concentrate on placing orders and reading positions, which is what most
trading bots need.

## Rules a library does not change [#rules-a-library-does-not-change]

Picking a library changes how you call the API, not what it does. These pages are
the single source for each rule, whichever language you choose:

<Cards>
<Card title="Authentication" href="/docs/authentication">
Tokens and scopes. All three send a personal access token, and none accepts a
browser sign-in token.
</Card>

<Card title="Conventions" href="/docs/conventions">
Micro units, price ticks, identifiers and the minimum order value.
</Card>

<Card title="Errors" href="/docs/errors">
Problem codes, recovery guidance, and which failures are worth retrying.
</Card>

<Card title="Rate limits" href="/docs/rate-limits">
The limits your client shares with every other caller.
</Card>

<Card title="Streaming" href="/docs/streaming">
Channels, sequence gaps, and what to do after a reconnect.
</Card>

<Card title="Account stream" href="/docs/account-stream">
Your own fills and order transitions on the private channel.
</Card>
</Cards>

## Point a client at this deployment [#point-a-client-at-this-deployment]

The API origin here is `https://app.agara.xyz` and its WebSocket origin is
`wss://app.agara.xyz`. Every snippet in these pages reads both from the
environment rather than hardcoding them, so the same code works wherever you
point it. Export them once:

```bash
export AGARA_BASE_URL="https://app.agara.xyz"
export AGARA_WS_URL="wss://app.agara.xyz"
export AGARA_CHAIN_ID="8453"
export AGARA_COLLATERAL_ADDRESS="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
export AGARA_CONDITIONAL_TOKENS_ADDRESS="0xe12D566cE5Dd8d817488E85a81386878649e3A18"
export AGARA_CTF_EXCHANGE_ADDRESS="0xD06f3fA925D35077A11dB42c6614D684f10B2aD6"
```

<Callout type="warn" title="This deployment uses real funds">
Confirm your client points at `https://app.agara.xyz` before sending an authenticated
request.
</Callout>

If none of the three libraries fits, the OpenAPI document at
`/trade/v1/openapi.json` on `https://app.agara.xyz` describes the whole REST surface.
Generate against the deployment you intend to call, so the server URL in the
generated client matches the environment you are pointing at.