Idempotency & amounts

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.

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.

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

{ "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.

"amount": "500000" for USDC_TRON (6 decimals) is 0.5 USDC. Check an asset’s decimals from List assets before formatting for display — don’t hardcode 6 or 18, some assets differ.

Get started

Core concepts

Webhooks

Idempotency & amounts

Idempotency

Amounts