> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootrush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdraw API

> API endpoints for creating and managing cryptocurrency withdrawals

## 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.

<Info>
  All endpoints require authentication via the `Authorization: Bearer <token>` header. Generate your API key at [Settings → API Key](https://www.lootrush.com/tokens/s/settings?tab=api-key).
</Info>

## Authentication

All requests must include an API token in the Authorization header:

```bash theme={null}
Authorization: Bearer your-api-token-here
```

<Warning>
  Unauthorized requests or requests for users not in the allowed list will
  return a `401 Unauthorized` response.
</Warning>

***

## Create Withdrawal

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

<Endpoint>
  <Method>POST</Method>
  <Path>/api/crypto/:userId/withdraw</Path>
</Endpoint>

### 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:

1. **Email address**: Must contain `@` symbol

   * Example: `user@example.com`

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: `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2`

<Info>
  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.
</Info>

### Example Request

```bash theme={null}
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

<ResponseField name="message" type="string">
  Status message indicating the withdrawal was created
</ResponseField>

<ResponseField name="data" type="object">
  <ResponseField name="bulkId" type="string">
    The unique identifier for the bulk payment operation (UUID format)
  </ResponseField>

  <ResponseField name="externalId" type="string">
    The external identifier you provided, if any
  </ResponseField>
</ResponseField>

### Example Response

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

### Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

| 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.

<Endpoint>
  <Method>GET</Method>
  <Path>/api/crypto/:userId/withdraws</Path>
</Endpoint>

### 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

```bash theme={null}
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

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="data" type="object">
  <ResponseField name="withdraws" type="array">
    Array of withdrawal objects. Each withdrawal includes:

    <ResponseField name="id" type="string">
      Entry ID
    </ResponseField>

    <ResponseField name="bulkId" type="string">
      Bulk payment ID
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the withdrawal entry
    </ResponseField>

    <ResponseField name="amountToPayToken" type="string">
      Amount to be paid (as string for precision)
    </ResponseField>

    <ResponseField name="outCurrencyIsoCode" type="string">
      Currency code (e.g., USDT)
    </ResponseField>

    <ResponseField name="toAddress" type="string">
      Recipient wallet address
    </ResponseField>

    <ResponseField name="externalId" type="string">
      External identifier, if provided
    </ResponseField>

    <ResponseField name="transactionHash" type="string">
      Blockchain transaction hash (if transaction has been processed)
    </ResponseField>

    <ResponseField name="transferTokenStatus" type="string">
      Status of the token transfer on the blockchain
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Error message, if the withdrawal failed
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the withdrawal was created
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of when the withdrawal was last updated
    </ResponseField>
  </ResponseField>

  <ResponseField name="pageInfo" type="object">
    <ResponseField name="limit" type="number">
      Number of results per page
    </ResponseField>

    <ResponseField name="offset" type="number">
      Number of results skipped (for pagination)
    </ResponseField>
  </ResponseField>
</ResponseField>

### Example Response

```json theme={null}
{
  "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)       |

<Info>
  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.
</Info>

***

## Rate Limits

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

***

## 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:

* Email: [support@lootrush.com](mailto:support@lootrush.com)
* Dashboard: [LootRush Dashboard](https://www.lootrush.com/tokens/s/dashboard)