Withdraw API

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. Generate your API key at Settings → API Key.

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

Parameter	Type	Required	Description
`userId`	string	Yes	The unique identifier of the user making the withdrawal

Request Body

Parameter	Type	Required	Default	Description
`amount`	string	Yes	-	The amount to withdraw (as a string to support precision)
`currency`	string	No	`USDT`	The cryptocurrency to withdraw (e.g., `USDT`, `USDC`, `EURC`)
`network`	string	No	`polygon`	The blockchain network (e.g., `polygon`, `ethereum`, `base`)
`to`	string	Yes	-	The recipient identifier. Can be an email address, user ID (UUID), or wallet address (0x-prefixed, 42 chars)
`externalId`	string	No	-	An optional external identifier for tracking this withdrawal in your system

Recipient Identifier (`to` parameter)

The to parameter accepts three formats:

Email address: Must contain @ symbol
- Example: [email protected]
User ID: Must be a valid UUID
- Example: 550e8400-e29b-41d4-a716-446655440000
Wallet address: Must start with 0x and be exactly 42 characters
- Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2

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": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
    "externalId": "withdraw-12345"
  }'

Response

string

Status message indicating the withdrawal was created

object

string

The unique identifier for the bulk payment operation (UUID format)

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

string

Error message describing what went wrong

Status Code	Error Message	Description
`401`	`Unauthorized`	Invalid or missing API token
`401`	`User not allowed`	The specified user is not in the allowed list
`404`	`User not found`	The specified userId does not exist
`404`	`Error finding user verified wallet`	Could not resolve the recipient identifier
`404`	`Wallet not found`	The resolved wallet address is invalid
`403`	`Receiver is not eligible to receive tokens`	The 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

Parameter	Type	Required	Description
`userId`	string	Yes	The unique identifier of the user whose withdrawals to retrieve

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default: `1`
`perPage`	number	No	Number of results per page. Default: `20`, Maximum: `200`
`bulkId`	string	No	Filter by bulk payment ID (UUID)
`transactionHash`	string	No	Filter by blockchain transaction hash
`status`	string	No	Filter by withdrawal status (e.g., `pending`, `queued`, `completed`)
`externalId`	string	No	Filter 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

string

Status message

object

array

Array of withdrawal objects. Each withdrawal includes:

string

Entry ID

string

Bulk payment ID

string

Current status of the withdrawal entry

string

Amount to be paid (as string for precision)

string

Currency code (e.g., USDT)

string

Recipient wallet address

string

External identifier, if provided

string

Blockchain transaction hash (if transaction has been processed)

string

Status of the token transfer on the blockchain

string

Error message, if the withdrawal failed

string

ISO 8601 timestamp of when the withdrawal was created

string

ISO 8601 timestamp of when the withdrawal was last updated

object

number

Number of results per page

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": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
        "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 Code	Error Message	Description
`401`	`Unauthorized`	Invalid or missing API token
`401`	`User not allowed`	The specified user is not in the allowed list
`404`	`User not found`	The specified userId does not exist

Withdrawal Statuses

Withdrawals progress through the following statuses:

Status	Description
`queued`	Withdrawal has been created and is waiting to be processed
`pending`	Withdrawal is being prepared for processing
`processing`	Withdrawal transaction is being executed on the blockchain
`completed`	Withdrawal has been successfully processed
`failed`	Withdrawal 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

Store the bulkId: Always store the bulkId returned from the Create Withdrawal endpoint for tracking and reconciliation purposes.
Use externalId: Provide a unique externalId when creating withdrawals to easily track them in your system.
Poll for status: After creating a withdrawal, periodically query the List Withdrawals endpoint using the bulkId or externalId to check the status.
Handle errors gracefully: Implement retry logic for transient errors, and handle blocked receivers appropriately.
Validate amounts: Ensure amounts are provided as strings to maintain precision for decimal values.
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:

Email: [email protected]
Dashboard: LootRush Dashboard

Getting started

API guides

MCP Server

Overview

Authentication

Create Withdrawal

Path Parameters

Request Body

Recipient Identifier (`to` parameter)

Example Request

Response

Example Response

Error Responses

List Withdrawals

Path Parameters

Query Parameters

Example Request

Response

Example Response

Error Responses

Withdrawal Statuses

Rate Limits

Best Practices

Support

​Overview

​Authentication

​Create Withdrawal

​Path Parameters

​Request Body

​Recipient Identifier (to parameter)

​Example Request

​Response

​Example Response

​Error Responses

​List Withdrawals

​Path Parameters

​Query Parameters

​Example Request

​Response

​Example Response

​Error Responses

​Withdrawal Statuses

​Rate Limits

​Best Practices

​Support

Overview

Authentication

Create Withdrawal

Path Parameters

Request Body

Recipient Identifier (`to` parameter)

Example Request

Response

Example Response

Error Responses

List Withdrawals

Path Parameters

Query Parameters

Example Request

Response

Example Response

Error Responses

Withdrawal Statuses

Rate Limits

Best Practices

Support