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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Processing",
   ...
}

Webhooks Examples

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

Webhook types: Transaction
resourceId: References the transaction ID

Processing:

{
  "tenantId": "2711ad4d-2c6b-4238-9f9d-2381d7a6d214",
  "action": "Create",
  "id": "e95503c4-f8bb-4f6b-89d3-42f10307a6bc",
  "resourceId": "b5787a92-82ba-4f09-bacc-02f57ea601ed",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T13:47:04.7710866Z",
  "changes": {
    "transactionStatus": "Processing"
  }
}

Completed:

{
  "tenantId": "36a6deef-8d5a-4560-b17d-e73f1dd3cd88",
  "action": "Update",
  "id": "4c01fdd9-923d-4ad9-9508-48a39cc85a3b",
  "resourceId": "6470d2bd-89e3-4e10-a3ff-605d820f8da3",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T14:06:04.1804263Z",
  "changes": {
    "transactionStatus": "Completed"
  }
}