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

# List Outlets

> List the outlets (agents or sub-businesses) under your merchant account

> [!NOTE]
>
> **Auth method: Signed (HMAC)** — this endpoint requires the full set of signed
> headers: `x-access-id`, `x-request-id`, `x-timestamp`, and an HMAC-SHA256
> `authorization` signature. See [Authentication](/api-reference/authentication.md#signed-hmac-authentication).

Returns a page of the outlets under your merchant account, most recently updated first.

Agent endpoints share a limit of 120 requests per minute. See [Rate limits](/api-reference/rate-limits.md).

## Headers

**authorization** `string` *required*

Base64-encoded HMAC-SHA256 signature of `{"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}`, signed with your access secret. The request body is not part of the signature.

**Example:** `"pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="`

**x-timestamp** `string` *required*

ISO 8601 timestamp; must be within 5 minutes of server time

**Example:** `"2026-10-15T09:45:53.000Z"`

**x-request-id** `string` *required*

A unique UUID v4 per request

**Example:** `"550e8400-e29b-41d4-a716-446655440000"`

**x-access-id** `string` *required*

Your API access ID provided by Tender

**Example:** `"your-access-id-here"`

## Query Parameters

**page** `number` (default: 1)

Page number, starting at 1

**Example:** `1`

**limit** `number` (default: 12)

Number of outlets per page

**Example:** `12`

**search** `string`

Case-insensitive text to match against the outlet's name, email, phone number, reference,
location or country

**Example:** `"lagos"`

## Response

**status** `string` *required*

Status of the API request

**Example:** `"success"`

**message** `string` *required*

Human-readable message describing the result

**Example:** `"success"`

**data** `object` *required*

A page of outlets

**data properties**

**agents** `array`

The outlets on this page

**outlet object**

**id** `string`

Outlet ID

**Example:** `"66f33b1fa9446a6b6b8f32cd"`

**reference** `string`

The outlet's Tender reference code

**Example:** `"vbibtucm9ynq3k2x7p"`

**name** `string`

Display name of the outlet

**Example:** `"Lagos Fashion Store"`

**email** `string`

Email address. Omitted if the outlet has none.

**Example:** `"lagosfashion@store.com"`

**phoneNumber** `string`

Phone number. Omitted if the outlet has none.

**Example:** `"+2348012345678"`

**location** `string`

Location of the outlet

**Example:** `"Lagos"`

**country** `string`

Country of the outlet

**Example:** `"Nigeria"`

**active** `boolean`

Whether the outlet is active

**Example:** `true`

**merchantId** `string`

ID of your merchant account

**Example:** `"6538e8f9bdec6d1a21978a64"`

**currency** `string`

The outlet's default fiat currency

**Example:** `"NGN"`

**totalSales** `string`

Total sales recorded for the outlet

**Example:** `"0"`

**defaultFiatCurrency** `object`

Default fiat currency settings: `currency` (string), `rate` (string) and
`useSystemRate` (boolean)

**createdAt** `string`

ISO 8601 timestamp when the outlet was created

**Example:** `"2026-10-15T09:45:53.000Z"`

**page** `number | string`

Current page number. Echoes the `page` query parameter as sent (a string) when you pass one.

**Example:** `1`

**pages** `number`

Total number of pages

**Example:** `1`

**limit** `number | string`

Outlets per page. Echoes the `limit` query parameter as sent (a string) when you pass one.

**Example:** `12`

**total** `number`

Total number of matching outlets

**Example:** `1`

## Example request

```bash theme={null}
curl "https://sandbox-api.tender.cash/v1/api/agent?search=lagos" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-timestamp: 2026-10-15T09:45:53.000Z" \
  -H "authorization: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="
```

## Example response

```json theme={null}
{
  "status": "success",
  "message": "success",
  "data": {
    "agents": [
      {
        "id": "66f33b1fa9446a6b6b8f32cd",
        "name": "Lagos Fashion Store",
        "email": "lagosfashion@store.com",
        "location": "Lagos",
        "country": "Nigeria",
        "active": true,
        "reference": "vbibtucm9ynq3k2x7p",
        "merchantId": "6538e8f9bdec6d1a21978a64",
        "currency": "NGN",
        "totalSales": "0",
        "defaultFiatCurrency": {
          "currency": "NGN",
          "rate": "1500",
          "useSystemRate": true
        },
        "createdAt": "2026-10-15T09:45:53.000Z"
      }
    ],
    "pages": 1,
    "page": 1,
    "limit": 12,
    "total": 1
  }
}
```


## OpenAPI

````yaml GET /v1/api/agent
openapi: 3.1.0
info:
  title: Tender API
  description: Tender Developer API for cryptocurrency payments and agent management
  version: 2.0.0
  contact:
    name: Tender Support
    url: https://tender.cash
servers:
  - url: https://secureapi.tender.cash
    description: Production Server
  - url: https://sandbox-api.tender.cash
    description: Sandbox Server
security:
  - SignedAuth: []
tags:
  - name: Agents
    description: Manage agents and sub-businesses
  - name: Transactions
    description: Payment and transaction operations
  - name: System
    description: System information and configuration
  - name: Webhooks
    description: Webhook management and logs
  - name: On-ramp
    description: Fiat-to-crypto on-ramp operations
  - name: Payouts
    description: Send crypto from merchant balance to a wallet address or payout account
  - name: Subwallets
    description: Provision and manage crypto wallet infrastructure for your end-users
  - name: Conversions
    description: Swap crypto between coins and chains, or convert to a payout account
paths:
  /v1/api/agent:
    get:
      tags:
        - Agents
      summary: List Outlets
      description: >-
        A page of the outlets (agents) under your merchant account, most
        recently updated first.
      operationId: getAgents
      parameters:
        - name: authorization
          in: header
          required: true
          description: >-
            Base64-encoded HMAC-SHA256 signature of
            `{"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}`,
            signed with your access secret. The request body is not part of the
            signature.
          schema:
            type: string
          example: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=
        - name: x-timestamp
          in: header
          required: true
          description: ISO 8601 timestamp; must be within 5 minutes of server time
          schema:
            type: string
            format: date-time
          example: '2026-10-15T09:45:53.000Z'
        - name: x-request-id
          in: header
          required: true
          description: A unique UUID v4 per request
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-access-id
          in: header
          required: true
          description: Your API access ID provided by Tender
          schema:
            type: string
          example: your-access-id-here
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 12
            minimum: 1
        - name: search
          in: query
          required: false
          description: Matches name, email, phone number, reference, location or country
          schema:
            type: string
      responses:
        '200':
          description: Outlets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentsResponse'
        '401':
          description: >-
            Missing headers, bad signature or timestamp outside the 5-minute
            window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsErrorResponse'
              example:
                status: error
                message: INVALID_REQUEST_SIGNATURE
                data: {}
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsErrorResponse'
              example:
                status: error
                message: Too many requests. Max 120 per 60s.
                data: null
      security:
        - SignedAuth: []
components:
  schemas:
    GetAgentsResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: success
        data:
          type: object
          properties:
            agents:
              type: array
              items:
                $ref: '#/components/schemas/Agent'
            page:
              type: number
              example: 1
            pages:
              type: number
              example: 1
            limit:
              type: number
              example: 12
            total:
              type: number
              example: 1
    PaymentsErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
        data:
          nullable: true
          description: Usually `null` or `{}`
    Agent:
      type: object
      properties:
        id:
          type: string
          example: 66f33b1fa9446a6b6b8f32cd
        reference:
          type: string
          example: vbibtucm9ynq3k2x7p
        name:
          type: string
          example: Lagos Fashion Store
        type:
          type: string
          description: Returned by create only
          example: online
        email:
          type: string
        phoneNumber:
          type: string
        location:
          type: string
        country:
          type: string
        active:
          type: boolean
        merchantId:
          type: string
        currency:
          type: string
          example: NGN
        totalSales:
          type: string
          example: '0'
        defaultFiatCurrency:
          type: object
          properties:
            currency:
              type: string
            rate:
              type: string
            useSystemRate:
              type: boolean
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    SignedAuth:
      type: apiKey
      in: header
      name: authorization
      description: >-
        Signed (HMAC) authentication. Required headers: x-access-id,
        x-request-id (UUID v4), x-timestamp (ISO 8601, must be within 5 minutes
        of server time), and authorization: the Base64 HMAC-SHA256 of the JSON
        string
        {"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}
        (keys in that order, no whitespace) using your access secret. The
        request body, method and path are not signed. The API key must be linked
        to an outlet.

````

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