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

# TypeScript and Python SDK setup and usage

> Install and configure the official Yoshi SDKs for TypeScript and Python. Includes usage examples, configuration options, error handling, and auto-pagination.

Official SDKs are available for TypeScript and Python. Both provide typed methods for every endpoint, automatic retries, and built-in pagination.

## Installation

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @yoshi-ai/sdk
  # or
  pnpm add @yoshi-ai/sdk
  ```

  ```bash Python theme={null}
  pip install yoshi-sdk
  # or
  uv add yoshi-sdk
  ```
</CodeGroup>

## Quick example

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Yoshi from "@yoshi-ai/sdk";

  const yoshi = new Yoshi(); // reads YOSHI_API_KEY from env

  const accounts = await yoshi.accounts.list();
  const scores = await yoshi.scores.list();
  const me = await yoshi.me.retrieve();
  const summary = await yoshi.me.summary();
  ```

  ```python Python theme={null}
  from yoshi import Yoshi

  yoshi = Yoshi()  # reads YOSHI_API_KEY from env

  accounts = yoshi.accounts.list()
  scores = yoshi.scores.list()
  me = yoshi.me.retrieve()
  summary = yoshi.me.summary()
  ```
</CodeGroup>

## Configuration

Both SDKs accept the same core options:

| Option                       | Default                 | Description                                    |
| ---------------------------- | ----------------------- | ---------------------------------------------- |
| `apiKey` / `api_key`         | `YOSHI_API_KEY` env var | Your API key (starts with `yoshi_`)            |
| `environment`                | `"production"`          | `"production"` or `"staging"`                  |
| `maxRetries` / `max_retries` | `2`                     | Maximum number of automatic retries on failure |
| `timeout`                    | `30000` ms / `30.0` s   | Request timeout                                |

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Yoshi from "@yoshi-ai/sdk";

  const yoshi = new Yoshi({
    apiKey: "yoshi_3xK9mP...",
    environment: "staging",
    maxRetries: 3,
    timeout: 60_000,
  });
  ```

  ```python Python theme={null}
  from yoshi import Yoshi

  yoshi = Yoshi(
      api_key="yoshi_3xK9mP...",
      environment="staging",
      max_retries=3,
      timeout=60.0,
  )
  ```
</CodeGroup>

## Auto-pagination

List endpoints return paginated results. The SDKs handle cursor-based pagination automatically with async iterators:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Iterate over all transactions automatically
  for await (const tx of yoshi.transactions.list({ limit: 100 })) {
    console.log(tx.merchant_name, tx.amount);
  }
  ```

  ```python Python (sync) theme={null}
  for tx in yoshi.transactions.list(limit=100):
      print(tx.merchant_name, tx.amount)
  ```

  ```python Python (async) theme={null}
  from yoshi import AsyncYoshi

  yoshi = AsyncYoshi()

  async for tx in yoshi.transactions.list(limit=100):
      print(tx.merchant_name, tx.amount)
  ```
</CodeGroup>

You can also fetch a single page:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const page = await yoshi.transactions.list({ limit: 50 });
  console.log(page.data);
  console.log(page.has_more);
  ```

  ```python Python theme={null}
  page = yoshi.transactions.list(limit=50)
  print(page.data)
  print(page.has_more)
  ```
</CodeGroup>

## Error handling

The SDKs raise typed exceptions for common HTTP error codes:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Yoshi from "@yoshi-ai/sdk";

  try {
    await yoshi.accounts.list();
  } catch (err) {
    if (err instanceof Yoshi.AuthenticationError) {
      // 401 — invalid or revoked API key
    } else if (err instanceof Yoshi.RateLimitError) {
      // 429 — rate limited
      console.log("Retry after:", err.headers["retry-after"]);
    } else if (err instanceof Yoshi.NotFoundError) {
      // 404 — resource not found
    }
  }
  ```

  ```python Python theme={null}
  from yoshi import Yoshi, AuthenticationError, RateLimitError, NotFoundError

  try:
      yoshi.accounts.list()
  except AuthenticationError:
      # 401 — invalid or revoked API key
      pass
  except RateLimitError as e:
      # 429 — rate limited
      print(f"Retry after: {e.response.headers['retry-after']}")
  except NotFoundError:
      # 404 — resource not found
      pass
  ```
</CodeGroup>

## Available resources

The SDKs expose methods that map directly to the API reference:

| SDK method                                | Endpoint                                    |
| ----------------------------------------- | ------------------------------------------- |
| `accounts.list()`                         | `GET /accounts`                             |
| `accounts.balanceSeries.list(id)`         | `GET /accounts/{id}/balances`               |
| `transactions.list()`                     | `GET /transactions`                         |
| `scores.list()`                           | `GET /scores`                               |
| `goals.list()`                            | `GET /goals`                                |
| `recurring.list()`                        | `GET /recurring`                            |
| `investments.list()`                      | `GET /investments`                          |
| `income.retrieve()`                       | `GET /income`                               |
| `me.retrieve()`                           | `GET /me`                                   |
| `me.summary()`                            | `GET /me/summary`                           |
| `paperTrading.accounts.create()`          | `POST /paper-trading/accounts`              |
| `paperTrading.accounts.list()`            | `GET /paper-trading/accounts`               |
| `paperTrading.accounts.trades.create(id)` | `POST /paper-trading/accounts/{id}/trades`  |
| `paperTrading.accounts.trades.list(id)`   | `GET /paper-trading/accounts/{id}/trades`   |
| `paperTrading.accounts.holdings.list(id)` | `GET /paper-trading/accounts/{id}/holdings` |
| `actions.create()`                        | `POST /actions`                             |
| `actions.list()`                          | `GET /actions`                              |
| `actions.retrieve(id)`                    | `GET /actions/{id}`                         |
| `approvals.retrieve(threadId)`            | `GET /approvals/{threadId}`                 |

<Note>
  Python method names use `snake_case` (e.g., `paper_trading.accounts.create()`).
</Note>

## Requirements

| SDK        | Minimum version |
| ---------- | --------------- |
| TypeScript | Node.js 18+     |
| Python     | Python 3.8+     |