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

# Utilities

> Helper functions for amount conversion, precision handling, and asset mapping

## Amount Conversion

### `toSmallestUnits` / `to_smallest_units`

Convert a display amount to the smallest unit (e.g., BTC to satoshis).

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { toSmallestUnits } from 'kaleido-sdk';

  const sats = toSmallestUnits(0.001, 8);   // 100000
  const usdt = toSmallestUnits(10.50, 2);   // 1050
  ```

  ```python Python theme={null}
  from kaleido_sdk import to_smallest_units

  sats = to_smallest_units(0.001, 8)   # 100000
  usdt = to_smallest_units(10.50, 2)   # 1050
  ```
</CodeGroup>

### `toDisplayUnits` / `to_display_units`

Convert from smallest units back to display units.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { toDisplayUnits } from 'kaleido-sdk';

  const btc = toDisplayUnits(100000, 8);   // 0.001
  const usd = toDisplayUnits(1050, 2);     // 10.50
  ```

  ```python Python theme={null}
  from kaleido_sdk import to_display_units

  btc = to_display_units(100000, 8)   # 0.001
  usd = to_display_units(1050, 2)     # 10.50
  ```
</CodeGroup>

### `toRawAmount` / `to_raw_amount`

Equivalent to `toSmallestUnits`. Convert display to raw.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { toRawAmount } from 'kaleido-sdk';

  const raw = toRawAmount(0.5, 8);  // 50000000
  ```

  ```python Python theme={null}
  from kaleido_sdk import to_raw_amount

  raw = to_raw_amount(0.5, 8)  # 50000000
  ```
</CodeGroup>

### `toDisplayAmount` / `to_display_amount`

Equivalent to `toDisplayUnits`. Convert raw to display.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { toDisplayAmount } from 'kaleido-sdk';

  const display = toDisplayAmount(50000000, 8);  // 0.5
  ```

  ```python Python theme={null}
  from kaleido_sdk import to_display_amount

  display = to_display_amount(50000000, 8)  # 0.5
  ```
</CodeGroup>

## PrecisionHandler

The `PrecisionHandler` manages amount conversions for multiple assets, using their metadata to look up precision automatically.

### Creating a PrecisionHandler

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { createPrecisionHandler } from 'kaleido-sdk';

  // MappedAsset objects with asset_id and precision
  const assets = [
    { asset_id: 'btc-asset-id', ticker: 'BTC', precision: 8, /* ... */ },
    { asset_id: 'usdt-asset-id', ticker: 'USDT', precision: 2, /* ... */ },
  ];

  const handler = createPrecisionHandler(assets);
  ```

  ```python Python theme={null}
  from kaleido_sdk import create_precision_handler

  assets = [
      {"asset_id": "btc-asset-id", "ticker": "BTC", "precision": 8},
      {"asset_id": "usdt-asset-id", "ticker": "USDT", "precision": 2},
  ]

  handler = create_precision_handler(assets)
  ```
</CodeGroup>

### Methods

#### `toRawAmount` / `to_raw_amount`

Convert display amount to raw, using the asset's precision.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const raw = handler.toRawAmount(0.5, 'btc-asset-id');  // 50000000
  ```

  ```python Python theme={null}
  raw = handler.to_raw_amount(0.5, "btc-asset-id")  # 50000000
  ```
</CodeGroup>

#### `toDisplayAmount` / `to_display_amount`

Convert raw amount to display.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const display = handler.toDisplayAmount(50000000, 'btc-asset-id');  // 0.5
  ```

  ```python Python theme={null}
  display = handler.to_display_amount(50000000, "btc-asset-id")  # 0.5
  ```
</CodeGroup>

#### `getAssetPrecision` / `get_asset_precision`

Get the precision for a specific asset.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const precision = handler.getAssetPrecision('btc-asset-id');  // 8
  ```

  ```python Python theme={null}
  precision = handler.get_asset_precision("btc-asset-id")  # 8
  ```
</CodeGroup>

#### `formatDisplayAmount` / `format_display_amount`

Format a display amount with the correct number of decimal places.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const formatted = handler.formatDisplayAmount(0.5, 'btc-asset-id');  // "0.50000000"
  ```

  ```python Python theme={null}
  formatted = handler.format_display_amount(0.5, "btc-asset-id")  # "0.50000000"
  ```
</CodeGroup>

#### `validateOrderSize` / `validate_order_size`

Validate an order amount against min/max limits.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = handler.validateOrderSize(0.001, btcAsset);
  // Returns: { valid: boolean, reason?: string }
  ```

  ```python Python theme={null}
  result = handler.validate_order_size(0.001, btc_asset)
  # Returns: ValidationResult { valid, reason }
  ```
</CodeGroup>

#### `getOrderSizeLimits` / `get_order_size_limits`

Get the min/max order size for an asset.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const limits = handler.getOrderSizeLimits(btcAsset);
  // Returns: { min: number, max: number }
  ```

  ```python Python theme={null}
  limits = handler.get_order_size_limits(btc_asset)
  # Returns: OrderSizeLimits { min, max }
  ```
</CodeGroup>

## AssetPairMapper (TypeScript)

The `AssetPairMapper` helps look up assets and trading pairs from the `listPairs` response. This utility is available in the TypeScript SDK.

### Creating a Mapper

```typescript theme={null}
import { createAssetPairMapper } from 'kaleido-sdk';

const pairsResponse = await client.maker.listPairs();
const mapper = createAssetPairMapper(pairsResponse);
```

### Methods

#### `findByTicker`

Find an asset by its ticker symbol.

```typescript theme={null}
const btc = mapper.findByTicker('BTC');
// Returns: MappedAsset | undefined
```

#### `findById`

Find an asset by its asset ID.

```typescript theme={null}
const asset = mapper.findById('btc-asset-id');
// Returns: MappedAsset | undefined
```

#### `getAllAssets`

Get all assets.

```typescript theme={null}
const allAssets = mapper.getAllAssets();
// Returns: MappedAsset[]
```

#### `canTrade` / `canTradeByTicker`

Check if two assets can be traded.

```typescript theme={null}
const canTrade = mapper.canTrade('btc-asset-id', 'usdt-asset-id');  // boolean
const canTradeByTicker = mapper.canTradeByTicker('BTC', 'USDT');     // boolean
```

#### `getTradingPartners`

Get all assets that can be traded with a given asset.

```typescript theme={null}
const partners = mapper.getTradingPartners('btc-asset-id');
// Returns: MappedAsset[]
```

#### `getActivePairs`

Get all active trading pairs.

```typescript theme={null}
const activePairs = mapper.getActivePairs();
// Returns: TradingPair[]
```

#### `findPairByTickers`

Find a specific pair by base and quote tickers.

```typescript theme={null}
const pair = mapper.findPairByTickers('BTC', 'USDT');
// Returns: TradingPair | undefined
```

## SDK Info

### `getVersion` / `get_version`

Get the SDK version string.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { getVersion } from 'kaleido-sdk';
  console.log(getVersion());  // "0.4.0"
  ```

  ```python Python theme={null}
  from kaleido_sdk import get_version
  print(get_version())  # "0.4.0"
  ```
</CodeGroup>

### `getSdkName` / `get_sdk_name`

Get the SDK package name.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { getSdkName } from 'kaleido-sdk';
  console.log(getSdkName());  // "kaleido-sdk"
  ```

  ```python Python theme={null}
  from kaleido_sdk import get_sdk_name
  print(get_sdk_name())  # "kaleido-sdk"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="file-code" href="/sdk/examples">
    See amount conversion used in real swap examples
  </Card>

  <Card title="Types" icon="brackets-curly" href="/sdk/types">
    Asset and TradingPair types that PrecisionHandler works with
  </Card>

  <Card title="Client Reference" icon="code" href="/sdk/api-reference">
    Full method reference including convenience toRaw / toDisplay methods
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sdk/troubleshooting">
    Precision and conversion edge cases
  </Card>
</CardGroup>