Crypto Wallet

📘
Customer account is required. See onboarding customer for more information.

To create a wallet and initiate a crypt withdrawal for a customer, follow these steps:

Create a wallet
Get wallet address
See wallet balance
Initiate crypto withdrawal
Monitor transfer status
Webhooks examples

1) Create a wallet

curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/wallets \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --data '{
   "customerId": "f3675f2e-da61-42e9-a9db-eef8bd4fb4e2",
   "network": "Sepolia" // Ethereum for production
}'

Response:

{
    "id": "d3a685f1-5803-4dc4-b63f-d9281879a686",
    "createdAtUtc": "2025-08-21T09:03:35.356903+00:00",
    "status": "Active",
    "customerId": "6da60529-9ba5-4370-88f7-a23e96041707",
    "cryptoDepositInstructions": [
        {
            "network": "Sepolia",
            "address": "0xafabec37213042e92af9d88e81dd00ea6120ab7d"
        }
    ]
}

2. Get wallet address

See API Reference

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/wallets/{walletId} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Response

{
    "id": "d3a685f1-5803-4dc4-b63f-d9281879a686",
    "createdAtUtc": "2025-08-21T09:03:35.356903+00:00",
    "status": "Active",
    "customerId": "6da60529-9ba5-4370-88f7-a23e96041707",
    "cryptoDepositInstructions": [
        {
            "network": "Sepolia",
            "address": "0xafabec37213042e92af9d88e81dd00ea6120ab7d"
        }
    ]
}

Add some test funds - Top up wallet balance

See API Reference

curl --request POST \
     --url https://api.sandbox.keyrails.com/api/v1/wallets/simulate-balance \
     --header 'Authorization: Authorization: Bearer {{AccessToken}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
{
  "walletAddress": "0x4d0280da2f2fDA5103914bCc5aad114743152A9c",
  "amount": "50000000",
  "tokenType": "USDC" // or USDT
}
'

3. See wallet balance

See API Reference

curl --request GET \
  --url https://api.sandbox.keyrails.com/api/v1/wallets/{walletId}/balance \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Response

[
  {
      "currency": "USDT",
      "network": "Sepolia",
      "total": 0
  },
  {
      "currency": "USDC",
      "network": "Sepolia",
      "total": 0
  }
]

4. Initiate Crypto withdrawal

curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/transfer \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
    "amount": 100.00,
    "customerId": "ad0305ac-cc5c-4a0b-95eb-f36d807792e9",
     "source": {
       "currency": "USDC",
       "network": "Sepolia",
       "walletId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
     },
     "destination": {
       "currency": "USDC",
       "network": "Sepolia",
       "toAddress": "0x4d0280da2f2fDA5103914bCc5aad114743152A9c"
     }
}'

Response:

{
  "id": "string",
  "transactionId": "string",
  "type": "WithdrawalCrypto",
  "status": "New",
  ...
}

Monitor Transfer Status

See API reference.

curl --request GET \
     --url https://api.sandbox.keyrails.com/api/v1/transactions/{transactionId} \
     --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 transfer.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "New",
  "trackingStatus": "string",
  "trackingReference": "string",
  "currency": "USD",
  "sourceCurrency": "USD",
  "destinationCurrency": "USD",
  "network": "Sepolia",
  "amount": 0,
  "cryptoAmount": 0,
  "transactionFee": 0,
  "appliedFee": 0,
  "totalAmount": 0,
  "comment": "string",
  "memo": "string",
  "purposeOfPayment": "string",
  "country": "string",
   ...
}

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"
  }
}

Failed:

{
  "tenantId": "36a6deef-8d5a-4560-b17d-e73f1dd3cd88",
  "action": "Update",
  "id": "44110cf3-05c4-4652-b718-fc0d6475453f",
  "resourceId": "6470d2bd-89e3-4e10-a3ff-605d820f8da3",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T14:07:01.6713778Z",
  "changes": {
    "transactionStatus": "Failed"
  }
}

Crypto deposit:

{
  "tenantId": "2711ad4d-2c6b-4238-9f9d-2381d7a6d214",
  "action": "Update",
  "id": "d58d77b2-396e-44b1-a918-90ca655d498b",
  "resourceId": "58a8bedd-7bda-4471-936d-f9d32191524f",
  "resourceType": "Transaction",
  "createdAtUtc": "2025-07-29T14:15:25.7333739Z",
  "changes": {
    "transactionStatus": "Completed",
    "transactionType": "DepositCrypto",
    "createdAt": "2025-07-29T14:11:10.8520000Z",
    "transactionHash": "0xf580ef78b69f2be786e539681d49a2948f5051486bdb5802361b51a16ba39cc7"
  }
}