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

# List withdrawals

> List withdrawals for the authenticated merchant with optional status filtering and pagination

## Overview

Returns merchant withdrawal history for the authenticated merchant. Withdrawals draw from the **withdrawal balance** only — if the needed funds are still in the collection balance, use [`POST /v1/merchant/balance/transfer`](/api-reference/merchant-balance/transfer-merchant-balance) to move them first.

Use this endpoint to track pending, submitted, settled, or failed withdrawals and to paginate through historical activity.

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your merchant API key
</ParamField>

## Query Parameters

<ParamField query="limit" type="integer">
  Number of results per page.

  **Default:** `50`
</ParamField>

<ParamField query="page" type="integer">
  Page number to retrieve.

  **Default:** `1`
</ParamField>

<ParamField query="status" type="string">
  Filter by withdrawal status.

  **Allowed values:** `PENDING`, `SUBMITTED`, `SETTLED`, `FAILED`
</ParamField>

## Request Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.daya.co/v1/merchant/withdrawals?status=SETTLED&limit=20' \
    --header 'X-Api-Key: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.daya.co/v1/merchant/withdrawals?status=SETTLED&limit=20',
    {
      headers: {
        'X-Api-Key': 'YOUR_API_KEY'
      }
    }
  );

  const withdrawals = await response.json();
  console.log(withdrawals);
  ```
</CodeGroup>

## Response

<ResponseField name="data" type="array">
  Withdrawal records matching the current filter.

  <Expandable title="withdrawal properties">
    <ResponseField name="id" type="string">
      Unique withdrawal identifier.
    </ResponseField>

    <ResponseField name="amount_usd" type="string">
      Withdrawal amount in USD.
    </ResponseField>

    <ResponseField name="fee_usd" type="string">
      Fee charged for the withdrawal, in USD.
    </ResponseField>

    <ResponseField name="token" type="string">
      Token sent on-chain.
    </ResponseField>

    <ResponseField name="chain" type="string">
      Destination chain.
    </ResponseField>

    <ResponseField name="destination_address" type="string">
      Recipient on-chain address.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current withdrawal status.
    </ResponseField>

    <ResponseField name="provider_tx_id" type="string">
      Provider-side transfer identifier, when available.
    </ResponseField>

    <ResponseField name="tx_hash" type="string">
      On-chain transaction hash, when available.
    </ResponseField>

    <ResponseField name="failure_code" type="string">
      Provider or platform failure code for failed withdrawals.
    </ResponseField>

    <ResponseField name="failure_message" type="string">
      Human-readable failure detail for failed withdrawals.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Time the withdrawal was created.
    </ResponseField>

    <ResponseField name="submitted_at" type="string">
      Time the withdrawal was submitted to the provider.
    </ResponseField>

    <ResponseField name="settled_at" type="string">
      Time the withdrawal was confirmed as settled.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update time for the withdrawal.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer" required>
  Current page number.
</ResponseField>

<ResponseField name="limit" type="integer" required>
  Results per page.
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of withdrawals matching filters.
</ResponseField>

<ResponseField name="total_pages" type="integer" required>
  Total number of pages available.
</ResponseField>

### Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "amount_usd": "12.3400",
        "fee_usd": "0.50",
        "token": "USDC",
        "chain": "SOLANA",
        "destination_address": "4vJ9JU1bJJE96FWSJN",
        "status": "SETTLED",
        "provider_tx_id": "transactions/abc123",
        "tx_hash": "4D5uX4exampleTxHash",
        "created_at": "2026-03-10T09:00:00Z",
        "submitted_at": "2026-03-10T09:01:00Z",
        "settled_at": "2026-03-10T09:03:00Z",
        "updated_at": "2026-03-10T09:03:00Z"
      }
    ],
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
  ```
</ResponseExample>

## Error Responses

This endpoint may return:

* `400`: Invalid query parameters
* `401`: Unauthorized
* `500`: Internal server error

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Withdrawal" icon="search" href="/api-reference/merchant-balance/get-withdrawal">
    Retrieve a single withdrawal by ID
  </Card>

  <Card title="Create Withdrawal" icon="paper-plane" href="/api-reference/merchant-balance/withdraw-merchant-balance">
    Initiate a new merchant balance withdrawal
  </Card>
</CardGroup>