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

# Idempotency & amounts

> Safe retries, and why amounts are strings

## Idempotency

Every mutating call takes an `idempotencyKey`. The same key and the same
request body always return the original result — a retry never double-
processes, and a repeat with a **different** body against the same key
is a `409 Conflict` rather than a silent overwrite.

> [!WARNING]
>
> Derive the key from your own domain object — an order id, a payout id,
> a signup id — never generate it randomly per attempt. A random key
> makes a timeout unrecoverable: you cannot tell whether the first call
> landed, and retrying pays twice.

```bash theme={null}
# Same key, same body: returns the original result, does not re-run it
curl https://api.keypair.io/v1/transactions \
  -d '{ "fromEntityId": "…", "idempotencyKey": "payout-order_44210", "amount": "50000", … }'
```

Retry on `429` (honouring `Retry-After`) and on `5xx`, always with the
**same** idempotency key.

## Amounts

Always **signed integer strings in minor units** — debits negative,
credits positive:

```json theme={null}
{ "asset": "USDC_TRON", "amount": "-500000" }
```

Never a JSON number. A `number` loses precision above 2^53, and native
assets need more precision than that: 1 ETH is 10^18 wei. A string
avoids silently rounding someone's withdrawal.

> [!TIP]
>
> `"amount": "500000"` for `USDC_TRON` (6 decimals) is 0.5 USDC. Check an
> asset's `decimals` from
> [List assets](https://docs.tetlith.com/api-reference/entities/list-assets-a-customer-account-can-be-opened-in.md)
> before formatting for display — don't hardcode 6 or 18, some assets
> differ.


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