Crypto Trading

📘
A wallet is required to initiate payment on behalf of a customer. See create crypto wallet for more information.

Trading consists of two steps:

1. Generate a Quote

Request a quote to retrieve the exchange rate and trade details.

The generated quote is valid for 15 seconds only. You must execute the trade within this time window

curl --request POST \
 --url https://api.sandbox.keyrails.com/api/v1/trades/quote \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{AccessToken}}' \
 --data '{
  "source": {
    "asset": "USDT",
    "network": "Ethereum",
    "amount": 10000
  },
  "destination": {
    "asset": "USDC",
    "network": "Ethereum"
  }
}'

Response

{
  "id": "cd653704-069e-4258-951c-6bd57704b5e8",
  "asset": "string",
  "network": "string",
  "source": {
    "asset": "USDC",
    "network": "Ethereum",
    "amount": 0
  },
  "destination": {
    "asset": "USDC",
    "network": "Ethereum"
  },
  "exchangeRate": 0,
  "quoteAmount": 0
}

2. Execute the Trade

Use the valid quote to complete the trade.

See API reference.

curl --request POST \
 --url https://api.sandbox.keyrails.com/api/v1/trades \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer {{AccessToken}}' \
 --data '{
  "quoteId": "cd653704-069e-4258-951c-6bd57704b5e8", 
  "walletId": "4cfd1069-5fb4-4753-8832-32d564c7fc14", // Wallet to execute the trade in
  "externalId": "4cfd1069-5fb4-4753-8832-32d564c7fc14", // Idempotency key
  "comment": "internal comment" // Optional
}'

Response

{
  "sellTransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "buyTransactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Monitor Status

See API reference.

curl --request GET \
     --url https://api.sandbox.keyrails.com/api/v1/transactions/{sellTransactionId} \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --header 'Authorization: Bearer {{AccessToken}}' \

Response:

The API responds with a transactionId, which can be used to track the buy and sell trades.

{
    "id": "2afe88bd-513c-4dd7-9a0e-509689b11a58",
    "type": "SellCrypto",
    "status": "Completed",
    "source": {
        "walletId": "0c54c91f-f924-4956-8a3a-fc7ae77f145a",
        "customerId": "09d1a671-5f97-4ec8-b488-65808bdee037"
    },
    "destination": {
        "customerId": "09d1a671-5f97-4ec8-b488-65808bdee037",
        "accountId": "0c54c91f-f924-4956-8a3a-fc7ae77f145a"
    },
    "sourceCurrency": "USDT",
    "destinationCurrency": "USDC",
    "network": "Sepolia",
    "transactionFee": 0,
    "totalAmount": 1000,
    "comment": "internal comment",
    "createdAt": "2026-04-16T05:47:30.298115+00:00",
    "updatedAt": "2026-04-16T05:49:03.572198+00:00"
}

Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions. Transaction type BuyCrypto and SellCrypto

Webhook types: Transaction
resourceId: References the transaction ID

Processing:

{
  "tenantId": "e9de9366-88db-4dcf-9dec-637c6339987e",
  "action": "Create",
  "id": "1834218d-a244-417e-a39d-e81b398a72b3",
  "resourceId": "371b2a7d-3263-4887-9bce-b3e8907ad6c3",
  "resourceType": "Transaction",
  "createdAtUtc": "2026-04-16T05:47:30.38359Z",
  "changes": {
    "transactionStatus": "Processing",
    "transactionType": "BuyCrypto"
  }
}

Completed:

{
  "tenantId": "e9de9366-88db-4dcf-9dec-637c6339987e",
  "action": "Update",
  "id": "c1b8b317-ff62-4f9b-a088-31e86b925124",
  "resourceId": "371b2a7d-3263-4887-9bce-b3e8907ad6c3",
  "resourceType": "Transaction",
  "createdAtUtc": "2026-04-16T05:53:21.7328255Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "BuyCrypto"
  }
}