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

# Merchant catalogue

> The live catalogue for rail selection: every merchant id /buy accepts, its display name, and whether this user still needs to link an account there. Same bearer scoping as POST /buy. Merchant ids are the public ids /buy uses in `placements[].merchant` and `unmatched[].merchant` (`retail` covers Amazon, Walmart, Target, Best Buy, Home Depot, Lowe's, Macy's, Wayfair, Staples, Kohl's and B&H Photo).



## OpenAPI

````yaml openapi.json GET /buy/merchants
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
  - name: Wallet funding
    description: >-
      Fund a connected user's wallet from your own UI — request a payment link,
      relay the phone verification code, and poll until the funds land.
  - name: Withdrawals
    description: >-
      Move money out of a connected user's wallet — to a saved bank account or a
      crypto address on Base. Transfers are processed manually by the Agentcard
      team, usually within 1-3 business days.
paths:
  /buy/merchants:
    get:
      tags:
        - Purchase
      summary: List the merchants /buy can place at
      description: >-
        The live catalogue for rail selection: every merchant id /buy accepts,
        its display name, and whether this user still needs to link an account
        there. Same bearer scoping as POST /buy. Merchant ids are the public ids
        /buy uses in `placements[].merchant` and `unmatched[].merchant`
        (`retail` covers Amazon, Walmart, Target, Best Buy, Home Depot, Lowe's,
        Macy's, Wayfair, Staples, Kohl's and B&H Photo).
      operationId: listBuyMerchants
      responses:
        '200':
          description: The catalogue.
          content:
            application/json:
              schema:
                type: object
                required:
                  - merchants
                properties:
                  merchants:
                    type: array
                    items:
                      type: object
                      required:
                        - slug
                        - name
                        - link_status
                      properties:
                        slug:
                          type: string
                          description: >-
                            The merchant id /buy uses (for example retail,
                            doordash, goodeggs, locale, flights).
                        name:
                          type: string
                          description: Display name.
                        tier:
                          type: string
                          description: How the merchant is integrated.
                        money_path:
                          type: string
                          description: How the merchant is paid.
                        link_status:
                          type: string
                          enum:
                            - ready
                            - linked
                            - pending
                            - error
                            - unlinked
                          description: >-
                            Whether this user can shop there now. ready: the
                            merchant needs no account link (retail, flights).
                            linked: the user's account is linked; shop now.
                            pending: a link was started and not finished; /buy
                            resumes it. error: the last link attempt failed;
                            /buy links it again. unlinked: no link yet; /buy
                            walks the user through it. Only ready and linked
                            place orders without a link step first.
                        capabilities:
                          type: array
                          items:
                            type: string
                          description: >-
                            What the merchant supports (search, cart,
                            scheduling, pickup, ...).
                        description:
                          type: string
                        unavailable:
                          type: object
                          description: >-
                            Present when checkout is temporarily unavailable at
                            this merchant, with the reason under `checkout`.
                          properties:
                            checkout:
                              type: string
        '401':
          description: Missing or invalid bearer.
      security:
        - userAccessToken: []
components:
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        A platform access token. Get one on the **Create an access token**
        endpoint by exchanging your `client_id` + `client_secret`, then send it
        as `Authorization: Bearer <token>`. Tokens live one hour.
    userAccessToken:
      type: http
      scheme: bearer
      description: >-
        The user's connection access_token (user authentication), or an
        org-minted buy_token for org-owned accounts.

````