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

# List merchants

> List the partner's merchants. Supports filtering by `status`, free-text `search` over name and ID, and cursor-based pagination via `cursor` and `limit`.



## OpenAPI

````yaml api/2026-02-19.preview.json GET /v1/merchants
openapi: 3.1.0
info:
  title: WalletConnect Pay API
  version: 2026-02-19.preview
servers:
  - url: https://api.pay.walletconnect.com
security:
  - API Key: []
  - ApiKey: []
  - AppId: []
tags:
  - name: Gateway
  - name: Payments
  - name: Refunds
  - name: Merchant Management
  - name: Settlements
  - name: Crypto Settlement
paths:
  /v1/merchants:
    get:
      tags:
        - Merchant Management
      summary: List merchants
      description: >-
        List the partner's merchants. Supports filtering by `status`, free-text
        `search` over name and ID, and cursor-based pagination via `cursor` and
        `limit`.
      operationId: MerchantManagement_list
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum:
              - active
              - inactive
              - suspended
          description: Filter by merchant status
        - in: query
          name: search
          schema:
            examples:
              - Acme
            type: string
            minLength: 1
            maxLength: 256
          description: Search by merchant name or ID (case-insensitive)
        - in: query
          name: cursor
          schema:
            type: string
          description: >-
            Opaque pagination cursor — use the value from `nextCursor` in the
            previous response.
        - in: query
          name: limit
          schema:
            default: 20
            type: integer
            minimum: 1
            maximum: 100
          description: Page size (default 20, max 100)
      responses:
        '200':
          description: Merchants list
          content:
            application/json:
              schema:
                type: object
                properties:
                  merchants:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Merchant ID
                          examples:
                            - mrch_7kBz2qR9xPvLmN4Yw
                        name:
                          description: Merchant display name
                          type: string
                        email:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Contact email
                          examples:
                            - billing@acme.store
                        status:
                          type: string
                          enum:
                            - active
                            - inactive
                            - suspended
                          description: Current merchant status
                          examples:
                            - active
                        iconUrl:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Merchant logo URL, or null if not set
                          examples:
                            - https://imagedelivery.net/example/acme-icon.png
                        createdAt:
                          type: string
                          description: ISO 8601 creation timestamp
                          examples:
                            - '2025-06-15T10:30:00.000Z'
                      required:
                        - id
                        - name
                        - email
                        - status
                        - iconUrl
                        - createdAt
                  totalCount:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: >-
                      Total number of merchants matching the query (ignoring
                      pagination)
                  nextCursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Cursor for the next page, or null if no more results
                required:
                  - merchants
                  - totalCount
                  - nextCursor
              example:
                merchants:
                  - id: mrch_7kBz2qR9xPvLmN4Yw
                    name: Acme Store
                    email: billing@acme.store
                    status: active
                    iconUrl: https://imagedelivery.net/example/acme-icon.png
                    createdAt: '2025-06-15T10:30:00.000Z'
                  - id: mrch_Qx8fTp3YwKjR5vNm2
                    name: Widget Co
                    email: null
                    status: active
                    iconUrl: null
                    createdAt: '2025-07-01T08:00:00.000Z'
                totalCount: 2
                nextCursor: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable error message
                  code:
                    type: string
                    enum:
                      - params_validation
                      - invalid_params
                    description: Machine-readable error code
                  details:
                    description: Additional structured error details
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties: {}
                  issues:
                    type: array
                    description: >-
                      Field-level validation issues (present on validation
                      errors)
                    items:
                      type: object
                      required:
                        - field
                        - message
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                required:
                  - message
                  - code
              examples:
                params_validation:
                  summary: Validation failed
                  value:
                    code: params_validation
                    message: Validation failed
                invalid_params:
                  summary: Invalid request parameters
                  value:
                    code: invalid_params
                    message: Invalid request parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable error message
                  code:
                    type: string
                    enum:
                      - missing_api_key
                      - invalid_api_key
                    description: Machine-readable error code
                  details:
                    description: Additional structured error details
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties: {}
                required:
                  - message
                  - code
              examples:
                missing_api_key:
                  summary: Missing API key
                  value:
                    code: missing_api_key
                    message: Missing API key
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    code: invalid_api_key
                    message: Invalid API key
components:
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: Api-Key
    ApiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: Private API key for wallet authentication
    AppId:
      type: apiKey
      in: header
      name: App-Id
      description: >-
        Public App ID for wallet authentication. When using this auth mode, the
        Client-Id header is also required.

````