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

# List Batch Items

> List the items in a specified payout batch using page-based pagination.

Supports `keyword` search. `page` defaults to 1 and `page_size` defaults to 10.

Merchant identity is determined by authentication through stablepay-auth. Do not include merchant\_id in request parameters. Batch statuses and business rules are determined by the StablePay Payout service.

## Authentication and Headers

Authenticate with a Bearer API Key and the three signing headers below. Compute HMAC-SHA256 over `{timestamp}.{nonce}.{requestBody}` with the API Secret, then encode the result as lowercase hex. Sign the exact request body bytes; use an empty string when no body is sent. See [Authentication and Signing](/en/api/getting-started#authentication-and-signing).

<ParamField header="Authorization" type="string" required>
  Bearer API Key: `Bearer sk_live_xxx`.
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix timestamp in seconds, within 5 minutes of the server time.
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  Random string for replay protection. Use a new nonce for each request. Minimum length: 16. Maximum length: 64.
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  Request signature encoded as lowercase hexadecimal.
</ParamField>

## Path Parameters

<ParamField path="batch_id" type="string" required>
  Minimum length: 1. Maximum length: 64.
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default={1}>
  Minimum: 1.
</ParamField>

<ParamField query="page_size" type="integer" default={10}>
  Minimum: 1. Maximum: 100.
</ParamField>

<ParamField query="keyword" type="string">
  Maximum length: 255.
</ParamField>

## Success Response

HTTP `200`, `application/json`. Query successful.

Only the fields defined below are allowed.

<ResponseField name="data" type="object[]" required>
  <Expandable title="Fields">
    Only the fields defined below are allowed.

    <ResponseField name="item_id" type="string" required />

    <ResponseField name="batch_id" type="string" required />

    <ResponseField name="merchant_order_id" type="string | null" />

    <ResponseField name="beneficiary_name" type="string" required />

    <ResponseField name="real_name" type="string" required />

    <ResponseField name="network" type="string" required>
      Allowed values: `erc20`, `trc20`, `spl`.
    </ResponseField>

    <ResponseField name="address" type="string" required />

    <ResponseField name="memo" type="string | null" />

    <ResponseField name="currency" type="string" required>
      Allowed values: `USDT`, `USDC`.
    </ResponseField>

    <ResponseField name="amount" type="string" required>
      Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
    </ResponseField>

    <ResponseField name="service_fee_amount" type="string" required>
      Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
    </ResponseField>

    <ResponseField name="debit_amount" type="string" required>
      Nonnegative decimal amount represented as a string, with at most two decimal places. Pattern: `^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Allowed values: `pending`, `processing`, `succeeded`, `failed`.
    </ResponseField>

    <ResponseField name="is_valid" type="boolean" required />

    <ResponseField name="validation_error" type="string | null" />

    <ResponseField name="tx_hash" type="string | null" />

    <ResponseField name="failure_code" type="string | null" />

    <ResponseField name="failure_message" type="string | null" />

    <ResponseField name="created_at" type="integer" required>
      Format: `int64`.
    </ResponseField>

    <ResponseField name="updated_at" type="integer" required>
      Format: `int64`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean" required />

<ResponseField name="total" type="integer" required>
  Format: `int64`. Minimum: 0.
</ResponseField>

### Response Headers

| Header | Description |
| - | - |
| `X-Request-ID` | Request tracing ID. |
| `Cache-Control` | The response must not be cached. Allowed values: `no-store`. |

## Error Responses

| HTTP | Description |
| - | - |
| 400 | Invalid HTTP request format or parameters, or the payout request failed business validation. Possible business error codes include address\_risk\_rejected, batch\_amount\_limit\_exceeded, batch\_amount\_too\_low, batch\_cannot\_submit, batch\_empty\_items, custody\_balance\_insufficient, insufficient\_balance, and quota\_blocked. |
| 401 | Authentication failed or a trusted merchant identity is missing. |
| 403 | The current merchant is not authorized to access or operate on this resource. |
| 404 | The specified payout batch or item does not exist. |
| 500 | A payout business error that is not currently classified more specifically. |
| 503 | The payout service timed out or is temporarily unavailable. If this occurs during a write request, query the resource status before retrying. |

Only the fields defined below are allowed.

<ResponseField name="code" type="integer" required />

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

<ResponseField name="errorCode" type="string" required />

<ResponseField name="data" type="null" required />

## Related Endpoints

* [Create Payout Batch](/en/api/payouts/create-batch)
* [Submit Payout Batch](/en/api/payouts/submit-batch)
* [Cancel Payout Batch](/en/api/payouts/cancel-batch)
* [Get Payout Batch](/en/api/payouts/get-batch)
* [List Payout Batches](/en/api/payouts/list-batches)
* [Get Payout Item](/en/api/payouts/get-item)

<RequestExample>
  Set `API_KEY` and `SECRET_KEY` before running this example. Set `BATCH_ID` or `ITEM_ID` when required by the endpoint.

  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  BODY=''
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --request GET --get "https://api.stablepay.co/api/v1/payout-batches/${BATCH_ID}/items" \
    --data-urlencode 'page=1' \
    --data-urlencode 'page_size=10' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 401 theme={"system"}
  {
    "code": 401,
    "message": "authenticated merchant is required",
    "errorCode": "authentication_required",
    "data": null
  }
  ```

  ```json 403 theme={"system"}
  {
    "code": 403,
    "message": "access denied",
    "errorCode": "forbidden",
    "data": null
  }
  ```

  ```json 404 theme={"system"}
  {
    "code": 404,
    "message": "batch not found",
    "errorCode": "batch_not_found",
    "data": null
  }
  ```

  ```json 500 theme={"system"}
  {
    "code": 500,
    "message": "payout request failed",
    "errorCode": "payout_error",
    "data": null
  }
  ```

  ```json 503 theme={"system"}
  {
    "code": 503,
    "message": "payout service is temporarily unavailable",
    "errorCode": "service_unavailable",
    "data": null
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.