Quickstart

This walks through the smallest real integration: one customer, one deposit address, one transaction. Every example uses a test key (kp_test_…) against KeyPair’s testnet — nothing here touches mainnet funds.

Every mutating call below takes an idempotencyKey. Derive it from your own domain object — an order id, a signup id — never generate it randomly. See Idempotency for why that matters the first time a request times out.

Create a customer

curl https://api.keypair.io/v1/entities \
  -H "Authorization: Bearer $KEYPAIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_8213",
    "displayName": "Amaka Obi",
    "idempotencyKey": "onboard-user_8213"
  }'

{
  "id": "5b6f8e2a-…",
  "externalId": "user_8213",
  "displayName": "Amaka Obi",
  "status": "active"
}

Open an account and issue a deposit address

curl https://api.keypair.io/v1/entities/5b6f8e2a-…/accounts \
  -H "Authorization: Bearer $KEYPAIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "asset": "USDC_TRON" }'

curl https://api.keypair.io/v1/entities/5b6f8e2a-…/address \
  -H "Authorization: Bearer $KEYPAIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "asset": "USDC_TRON" }'

{ "address": "TXYZ…", "chain": "tron", "asset": "USDC_TRON" }

Send this address to your customer, or render it as a QR code. Once the chain confirms a deposit, you’ll get a deposit.confirmed webhook and the balance lands in their account — no polling required.

Move money

Balances move out with a single signed request, to another customer of yours (toEntityId) or to a blockchain address (toAddress) — see Authentication for why moving money is signed rather than bearer-only.

cURL

curl https://api.keypair.io/v1/transactions \
  -H "x-keypair-key-id: $KEYPAIR_KEY_ID" \
  -H "x-keypair-timestamp: $TIMESTAMP" \
  -H "x-keypair-nonce: $NONCE" \
  -H "x-keypair-signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "fromEntityId": "5b6f8e2a-…",
    "asset": "USDC_TRON",
    "amount": "500000",
    "toAddress": "TDestinationAddress00000000000000",
    "idempotencyKey": "payout-order_9821"
  }'

Check the balance

cURL

curl https://api.keypair.io/v1/accounts/balance?accountId=… \
  -H "Authorization: Bearer $KEYPAIR_KEY"

Amounts are always signed integer strings in minor units — see why in Idempotency & amounts.

Every event you can receive

deposit.confirmed, withdrawal.finalised, and four others — with the exact payload for each.

The full set of endpoints, grouped the same way as this guide, is in the API Reference tab above.

Get started

Core concepts

Webhooks

Next

Every event you can receive