Skip to main content

Crypto APIs

Crypto APIs

The Crypto API provides endpoints for managing blockchain operations including deposit address generation, withdrawals, transaction verification, and balance inquiries. All endpoints are authenticated using your API key and HMAC signature as described in Authentication & Security.

Overview​

All crypto endpoints are served under:

https://api.keshflippay.com/api/v1/crypto

These APIs enable partners to integrate digital asset transactions securely across multiple chains and supported tokens.

1. Create Deposit Address​

Generate a new deposit address for a specific asset and blockchain.

Endpoint

POST /api/v1/crypto/addresses/create

Headers

NameDescription
X-keshflippay-KeyYour public API key
X-keshflippay-TimestampCurrent UNIX timestamp
X-keshflippay-SignatureHMAC-SHA256 signature
Content-Typeapplication/json

Request Example

{
  "chainId": "1",
  "asset": "USDC",
  "label": "main_wallet",
  "metadata": { "environment": "production" }
}

cURL Example

Terminal
curl -X POST "https://api.keshflippay.com/api/v1/crypto/addresses/create" \
-H "Content-Type: application/json" \
-H "X-keshflippay-Key: <api_key>" \
-H "X-keshflippay-Timestamp: $(date +%s)" \
-H "X-keshflippay-Signature: <signature>" \
-d '{"chainId":"1","asset":"USDC","label":"main_wallet"}'

Response Example

{
  "addressId": "addr_01HXYJFG82R12X",
  "address": "0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7",
  "asset": "USDC",
  "chainId": "1",
  "status": "ACTIVE",
  "createdAt": "2025-10-10T12:00:00Z"
}

2. List Deposit Addresses​

Retrieve all deposit addresses created under your account.

Endpoint

GET /api/v1/crypto/addresses

Headers

NameDescription
X-keshflippay-KeyYour public API key
X-keshflippay-TimestampCurrent UNIX timestamp
X-keshflippay-SignatureHMAC-SHA256 signature

Response Example

{
  "status": "success",
  "data": [
    {
      "addressId": "addr_01HXYJFG82R12X",
      "address": "0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7",
      "asset": "USDC",
      "chainId": "1",
      "createdAt": "2025-10-10T12:00:00Z"
    },
    {
      "addressId": "addr_01HXYJFG82R13B",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "asset": "ETH",
      "chainId": "1",
      "createdAt": "2025-10-12T09:23:00Z"
    }
  ]
}

3. Estimate Network Fee​

Estimate blockchain network fees before creating a withdrawal.

Endpoint

POST /api/v1/crypto/withdrawals/network-fee

Request Example

{
  "chainId": "1",
  "asset": "USDC",
  "amount": "100.00",
  "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

Response Example

{
  "status": "success",
  "data": {
    "networkFee": "0.00042",
    "currency": "ETH",
    "finalAmount": "99.99958"
  },
  "message": "Fee estimated successfully."
}

4. Create Withdrawal​

Initiate a blockchain withdrawal request.

Endpoint

POST /api/v1/crypto/withdrawals

Request Example

{
  "chainId": "1",
  "asset": "USDC",
  "amount": "250.00",
  "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "reference": "invoice_3029",
  "idempotencyKey": "withdrawal_001"
}

Response Example

{
  "status": "success",
  "data": {
    "withdrawalId": "wd_001",
    "transactionHash": "0xabc1234def567...",
    "status": "PENDING",
    "createdAt": "2025-10-12T15:24:00Z"
  },
  "message": "Withdrawal created successfully."
}

5. Verify Transaction​

Validate an existing blockchain transaction to confirm its status and amount.

Endpoint

POST /api/v1/crypto/verify-transaction

Request Example

{
  "chainId": "1",
  "asset": "USDC",
  "txHash": "0xabc1234def567...",
  "expectedAmount": "100.00"
}

Response Example

{
  "status": "success",
  "data": {
    "verified": true,
    "confirmations": 12,
    "blockHeight": 21039485,
    "timestamp": "2025-10-12T15:29:00Z"
  },
  "message": "Transaction verified."
}

6. Create Deposit (Legacy Flow)​

Use this endpoint if you manage fixed or per-session deposits.

Endpoint

POST /api/v1/crypto/deposits

Request Example

{
  "partnerId": "partner_001",
  "chainId": "1",
  "asset": "USDC",
  "amount": "500.00",
  "idempotencyKey": "deposit_001",
  "reference": "order_9002"
}

Response Example

{
  "status": "success",
  "data": {
    "depositId": "dep_001",
    "address": "0xabc123...",
    "chainId": "1",
    "asset": "USDC",
    "amount": "500.00",
    "status": "PENDING",
    "expiresAt": "2025-10-13T12:00:00Z"
  },
  "message": "Deposit created successfully."
}

7. Get Deposit Details​

Retrieve deposit information by ID.

Endpoint

GET /api/v1/crypto/deposits/:id

Response Example

{
  "status": "success",
  "data": {
    "depositId": "dep_001",
    "asset": "USDC",
    "chainId": "1",
    "amount": "500.00",
    "status": "CONFIRMED",
    "txHash": "0xabc123...",
    "confirmedAt": "2025-10-12T16:10:00Z"
  }
}

8. Get Partner Balances​

Retrieve your current crypto balances for supported chains and assets.

Endpoint

GET /api/v1/crypto/balances/:partnerId

Response Example

{
  "status": "success",
  "data": [
    {
      "asset": "USDC",
      "chainId": "1",
      "available": "12500.00",
      "locked": "500.00"
    },
    {
      "asset": "ETH",
      "chainId": "1",
      "available": "4.25",
      "locked": "0.25"
    }
  ]
}

9. Error Handling​

All crypto endpoints return standard API responses containing:

  • status: "success" or "error"
  • message: additional context
  • data: object or array, depending on request type

See Error Codes & Troubleshooting for detailed status codes and formats.

10. Rate Limits​

All API requests are subject to rate limits.

Headers

HeaderDescription
X-RateLimit-LimitMax requests per minute
X-RateLimit-RemainingRemaining requests in the current window
X-RateLimit-ResetTimestamp when the limit resets