> ## 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+ |


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