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

# SDK helpers for currency, idempotency, and conversions

> Use Yoshi SDK helper functions to format currency amounts, generate idempotency keys for POST requests, and convert between cents and dollars.

Both SDKs include convenience helpers for common tasks. These are custom modules that ship alongside the generated SDK code.

## Format amounts

Format a numeric amount as a localized currency string:

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

  formatAmount(1234.5, "USD");         // "$1,234.50"
  formatAmount(1234.5, "EUR", "de-DE"); // "1.234,50 €"
  formatAmount(999, "JPY");            // "¥999"
  ```

  ```python Python theme={null}
  from yoshi.lib.helpers import format_amount

  format_amount(1234.5, "USD")   # "$1,234.50"
  format_amount(1234.5, "EUR")   # "1,234.50 €"
  format_amount(999, "JPY")      # "¥999"
  ```
</CodeGroup>

The TypeScript helper uses `Intl.NumberFormat` for locale-aware formatting. The Python helper uses a built-in currency symbol map and is thread-safe.

### Supported currencies

The Python helper includes built-in formatting for: USD, EUR, GBP, JPY, CAD, AUD, MXN, BRL, CNY, INR, KRW, and CHF. The TypeScript helper supports any currency code recognized by `Intl.NumberFormat`.

## Generate idempotency keys

Generate a unique key for POST requests to prevent duplicate operations:

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

  const key = generateIdempotencyKey();
  // "idk_a1b2c3d4e5f67890a1b2c3d4e5f67890"
  ```

  ```python Python theme={null}
  from yoshi.lib.helpers import generate_idempotency_key

  key = generate_idempotency_key()
  # "idk_a1b2c3d4e5f67890a1b2c3d4e5f67890"
  ```
</CodeGroup>

Keys are prefixed with `idk_` followed by 32 random hex characters. Pass the key in the `Idempotency-Key` header or the `idempotency_key` field on supported endpoints like `POST /actions`:

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

  const yoshi = new Yoshi();

  // The SDK sends the key in the Idempotency-Key header automatically
  const action = await yoshi.actions.create({
    action_type: "paper_trade",
    idempotency_key: generateIdempotencyKey(),
    proposal_data: { /* ... */ },
  });
  ```

  ```python Python theme={null}
  from yoshi import Yoshi
  from yoshi.lib.helpers import generate_idempotency_key

  yoshi = Yoshi()

  action = yoshi.actions.create(
      action_type="paper_trade",
      idempotency_key=generate_idempotency_key(),
      proposal_data={ ... },
  )
  ```
</CodeGroup>

If a duplicate key is detected for the same user, the API returns a `409 Conflict` response.

## Convert between cents and dollars

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { centsToDollars, dollarsToCents } from "@yoshi-ai/sdk/lib/helpers";

  centsToDollars(1050);   // 10.5
  dollarsToCents(10.5);   // 1050
  dollarsToCents(19.99);  // 1999
  ```

  ```python Python theme={null}
  from yoshi.lib.helpers import cents_to_dollars, dollars_to_cents

  cents_to_dollars(1050)   # 10.5
  dollars_to_cents(10.5)   # 1050
  dollars_to_cents(19.99)  # 1999
  ```
</CodeGroup>

`dollarsToCents` / `dollars_to_cents` rounds the result to avoid floating-point precision issues.