Skip to main content

​
Overview

The Withdraw API allows third-party partners to initiate cryptocurrency withdrawals on behalf of users and retrieve withdrawal history. All endpoints require API token authentication and are scoped to specific users.
All endpoints require authentication via the Authorization: Bearer <token> header. Contact your LootRush account manager to obtain your API token.

​
Authentication

All requests must include an API token in the Authorization header: 
Authorization: Bearer your-api-token-here
Unauthorized requests or requests for users not in the allowed list will return a 401 Unauthorized response.

​
Create Withdrawal

Initiates a cryptocurrency withdrawal request for a user. The withdrawal is created as a queued transaction and processed asynchronously.

​
Path Parameters

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user making the withdrawal

​
Request Body

ParameterTypeRequiredDefaultDescription
amountstringYes-The amount to withdraw (as a string to support precision)
currencystringNoUSDTThe cryptocurrency to withdraw (e.g., USDT, USDC)
networkstringNopolygonThe blockchain network (e.g., polygon, ethereum)
tostringYes-The recipient identifier. Can be an email address, user ID (UUID), or wallet address (0x-prefixed, 42 chars)
externalIdstringNo-An optional external identifier for tracking this withdrawal in your system

​
Recipient Identifier (to parameter)

The to parameter accepts three formats:
  1. Email address: Must contain @ symbol
  2. User ID: Must be a valid UUID
    • Example: 550e8400-e29b-41d4-a716-446655440000
  3. Wallet address: Must start with 0x and be exactly 42 characters
    • Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
When an email or user ID is provided, the system will automatically resolve it to the user’s verified smart wallet address. If a wallet address is provided directly, it will be used as-is.

​
Example Request

curl -X POST https://third-party.lootrush.com/api/crypto/550e8400-e29b-41d4-a716-446655440000/withdraw \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.50",
    "currency": "USDT",
    "network": "polygon",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "externalId": "withdraw-12345"
  }'

​
Response

​
message
string
Status message indicating the withdrawal was created
​
data
object
​
bulkId
string
The unique identifier for the bulk payment operation (UUID format)
​
externalId
string
The external identifier you provided, if any

​
Example Response

{
  "message": "Withdraw created as queued",
  "data": {
    "bulkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "withdraw-12345"
  }
}

​
Error Responses

​
error
string
Error message describing what went wrong
Status CodeError MessageDescription
401UnauthorizedInvalid or missing API token
401User not allowedThe specified user is not in the allowed list
404User not foundThe specified userId does not exist
404Error finding user verified walletCould not resolve the recipient identifier
404Wallet not foundThe resolved wallet address is invalid
403Receiver is not eligible to receive tokensThe recipient wallet is blocked from receiving tokens

​
List Withdrawals

Retrieves a paginated list of withdrawal transactions for a user. Supports filtering by various criteria.

​
Path Parameters

ParameterTypeRequiredDescription
userIdstringYesThe unique identifier of the user whose withdrawals to retrieve

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number (1-indexed). Default: 1
perPagenumberNoNumber of results per page. Default: 20, Maximum: 200
bulkIdstringNoFilter by bulk payment ID (UUID)
transactionHashstringNoFilter by blockchain transaction hash
statusstringNoFilter by withdrawal status (e.g., pending, queued, completed)
externalIdstringNoFilter by external identifier you provided when creating the withdrawal

​
Example Request

curl -X GET "https://third-party.lootrush.com/api/crypto/550e8400-e29b-41d4-a716-446655440000/withdraws?page=1&perPage=20&status=queued" \
  -H "Authorization: Bearer your-api-token-here"

​
Response

​
message
string
Status message
​
data
object
​
withdraws
array
Array of withdrawal objects. Each withdrawal includes:
​
id
string
Entry ID
​
bulkId
string
Bulk payment ID
​
status
string
Current status of the withdrawal entry
​
amountToPayToken
string
Amount to be paid (as string for precision)
​
outCurrencyIsoCode
string
Currency code (e.g., USDT)
​
toAddress
string
Recipient wallet address
​
externalId
string
External identifier, if provided
​
transactionHash
string
Blockchain transaction hash (if transaction has been processed)
​
transferTokenStatus
string
Status of the token transfer on the blockchain
​
errorMessage
string
Error message, if the withdrawal failed
​
createdAt
string
ISO 8601 timestamp of when the withdrawal was created
​
updatedAt
string
ISO 8601 timestamp of when the withdrawal was last updated
​
pageInfo
object
​
limit
number
Number of results per page
​
offset
number
Number of results skipped (for pagination)

​
Example Response

{
  "message": "Withdraw created as queued",
  "data": {
    "withdraws": [
      {
        "id": "entry-123",
        "bulkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "queued",
        "amountToPayToken": "100.50",
        "outCurrencyIsoCode": "USDT",
        "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "externalId": "withdraw-12345",
        "transactionHash": null,
        "transferTokenStatus": null,
        "errorMessage": null,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pageInfo": {
      "limit": 20,
      "offset": 0
    }
  }
}

​
Error Responses

Status CodeError MessageDescription
401UnauthorizedInvalid or missing API token
401User not allowedThe specified user is not in the allowed list
404User not foundThe specified userId does not exist

​
Withdrawal Statuses

Withdrawals progress through the following statuses:
StatusDescription
queuedWithdrawal has been created and is waiting to be processed
pendingWithdrawal is being prepared for processing
processingWithdrawal transaction is being executed on the blockchain
completedWithdrawal has been successfully processed
failedWithdrawal failed (check errorMessage for details)
Withdrawals are processed asynchronously. After creating a withdrawal, use the bulkId returned in the response to query the withdrawal status via the List Withdrawals endpoint.

​
Rate Limits

Rate limits may apply. Contact your LootRush account manager for specific rate limit information for your integration.

​
Best Practices

  1. Store the bulkId: Always store the bulkId returned from the Create Withdrawal endpoint for tracking and reconciliation purposes.
  2. Use externalId: Provide a unique externalId when creating withdrawals to easily track them in your system.
  3. Poll for status: After creating a withdrawal, periodically query the List Withdrawals endpoint using the bulkId or externalId to check the status.
  4. Handle errors gracefully: Implement retry logic for transient errors, and handle blocked receivers appropriately.
  5. Validate amounts: Ensure amounts are provided as strings to maintain precision for decimal values.
  6. Monitor transaction hashes: Once a withdrawal has a transactionHash, you can track it on the blockchain explorer for the respective network.

​
Support

For API support, please contact: