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

# Market Snapshot

> Retrieve the daily NGX market summary.

The snapshot endpoint gives you a complete picture of any single NGX trading day in one request.

You get the All Share Index (ASI) level (`asi`), its absolute and percentage change, naira value traded, total deals, share volume, and a market capitalisation breakdown across equities, bonds, and ETFs. The response also includes:

* **`breadth`** — how many securities advanced, declined, or were unchanged in that session, plus the advance/decline ratio.
* **`ytd_asi_change_percent`** — ASI return from the first trading day of the year, useful for YTD performance widgets.
* **`turnover_rate`** — value traded as a percentage of equity market cap, a quick liquidity signal.
* **`total_listed_securities`** — total companies listed on NGX.
* **`session`** — NGX trading hours (`10:00–14:30 WAT`).

When no date is supplied the API returns the most recent available trading day automatically.

To pull a specific historical day, pass `date` as `YYYY-MM-DD`:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.ngnmarket.com/v1/market/snapshot?date=2026-04-17" \
    -H "Authorization: Bearer ngm_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://api.ngnmarket.com/v1/market/snapshot');
  url.searchParams.set('date', '2026-04-17');

  const res = await fetch(url, {
    headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' },
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      'https://api.ngnmarket.com/v1/market/snapshot',
      params={'date': '2026-04-17'},
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

If the date is a weekend, public holiday, or any other non-trading day, the API responds with `404 NOT_FOUND`. You can confirm valid dates with [`GET /market/available-dates`](/api-reference/market/available-dates).


## OpenAPI

````yaml GET /market/snapshot
openapi: 3.1.0
info:
  title: NGN Market API
  version: '1.0'
  description: >
    The NGN Market API provides programmatic access to Nigerian Exchange Group
    (NGX) market data, including equities, forex rates, company profiles,
    indices, bonds, and financial news.


    ## Base URL


    All endpoints are served from:


    ```

    https://api.ngnmarket.com/v1

    ```


    ## Authentication


    Every request requires a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer ngm_live_YOUR_KEY

    ```


    Generate and manage your API keys from the [developer
    dashboard](https://ngnmarket.com/developer).


    ## Plans & Quotas


    | Plan | Monthly Calls | Requests/min | Price |

    | :--- | ---: | ---: | :--- |

    | Free | 3,000 | 30 | Free |

    | Hobby | 10,000 | 60 | ₦15,000/mo |

    | Starter | 100,000 | 120 | ₦50,000/mo |

    | Growth | 500,000 | 200 | ₦200,000/mo |

    | Business | 2,000,000 | 300 | ₦700,000/mo |

    | Enterprise | Unlimited | Unlimited | Custom |


    Every response includes a `meta` object showing your current usage and
    remaining quota. Exceeding the per-minute rate limit returns `429
    RATE_LIMITED`. Exceeding the monthly quota returns `429 QUOTA_EXCEEDED`.


    ## Response Envelope


    All responses use a consistent JSON envelope:


    ```json

    {
      "success": true,
      "data": { ... },
      "meta": {
        "plan": "starter",
        "calls_used": 4821,
        "calls_remaining": 95179,
        "reset_at": "2026-05-01T00:00:00.000Z"
      }
    }

    ```
  contact:
    name: NGN Market Support
    email: support@ngnmarket.com
    url: https://ngnmarket.com
  license:
    name: Proprietary
servers:
  - url: https://api.ngnmarket.com/v1
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Market
    description: >-
      Daily market snapshots, top trades, movers, market breadth, sectors, and
      YTD performers.
  - name: Companies
    description: >-
      Browse, search, and retrieve profiles, price charts, and financial
      statements for NGX-listed companies.
  - name: Forex
    description: Current and historical NGN exchange rates against major currencies.
  - name: Indices
    description: >-
      All NGX market indices, including list, detail with constituents, and
      historical chart data.
  - name: ETFs
    description: >-
      NGX-listed Exchange Traded Funds and ETPs — list, full fund detail, and
      historical daily price data.
  - name: Bonds
    description: >-
      NGX-listed bond instruments with issuer details, coupon rates, and
      maturity dates.
  - name: Disclosures
    description: >-
      Official corporate filings from NGX-listed companies (financial
      statements, AGM notices, board meetings, director dealings, earnings
      forecasts). Sourced from NGX Group and updated twice daily.
  - name: Blog
    description: >-
      Published NGN Market blog posts. List, search, and filter by category or
      company.
  - name: Dividends
    description: >-
      Market-wide NGX dividend calendar. Browse upcoming and recently paid
      dividends across all listed companies with optional search and pagination.
  - name: Account
    description: >-
      Quota status, 30-day request analytics, and paginated request logs for the
      authenticated user.
paths:
  /market/snapshot:
    get:
      tags:
        - Market
      summary: Daily NGX market summary
      description: >
        Returns the full daily market summary for a given trading date: ASI
        level and change, total deals, volume, naira value traded, and a
        market-capitalisation breakdown across equities, bonds, and ETFs. Omit
        the `date` parameter to receive the most recent available trading day.


        When queried without a `date` during NGX trading hours (Monday–Friday,
        09:00–16:00 WAT), this reflects an intraday snapshot updated every 20
        minutes.


        **Plan required:** Free
      operationId: getMarketSnapshot
      parameters:
        - name: date
          in: query
          description: >-
            Trading date in `YYYY-MM-DD` format (e.g. `2026-04-17`). Omit for
            the latest available snapshot.
          required: false
          schema:
            type: string
            format: date
            example: '2026-04-17'
      responses:
        '200':
          description: Market snapshot retrieved successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/MarketSnapshot'
              examples:
                latestSnapshot:
                  summary: Latest trading day snapshot
                  value:
                    success: true
                    data:
                      date: '2026-04-17'
                      asi: 105432.18
                      asi_change: 876.44
                      asi_change_percent: 0.84
                      ytd_asi_change_percent: 12.37
                      deals: 4821
                      volume: 312847291
                      value_traded: 4821093847
                      turnover_rate: 0.0093
                      market_cap:
                        equity: 52109847302
                        bonds: 5100000000
                        etfs: 1081200000
                        total: 58291047302
                      breadth:
                        advancers: 38
                        decliners: 21
                        unchanged: 14
                        total: 73
                        adv_dec_ratio: 1.81
                      total_listed_securities: 158
                      session:
                        open_time: '10:00'
                        close_time: '14:30'
                        timezone: Africa/Lagos
                      updated_at: '2026-04-17T18:00:00.000Z'
                    meta:
                      plan: free
                      calls_used: 1
                      calls_remaining: 9999
                      reset_at: '2026-05-01T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No snapshot found for the requested date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: No snapshot found for 2026-01-01.
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          const: true
        meta:
          $ref: '#/components/schemas/Meta'
    MarketSnapshot:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Trading date in YYYY-MM-DD format.
          example: '2026-04-17'
        asi:
          type: number
          description: Closing All Share Index value.
          example: 105432.18
        asi_change:
          type: number
          description: Absolute change in ASI from the previous trading day.
          example: 876.44
        asi_change_percent:
          type: number
          description: Percentage change in the ASI from the previous trading day.
          example: 0.84
        deals:
          type: integer
          description: Total deals executed during the session.
          example: 4821
        volume:
          type: integer
          description: Total shares traded.
          example: 312847291
        value_traded:
          type: number
          description: Total naira value of all trades.
          example: 4821093847
        market_cap:
          type: object
          properties:
            equity:
              type: number
              description: Equity market capitalisation (NGN).
              example: 52109847302
            bonds:
              type: number
              description: Bond market capitalisation (NGN).
              example: 5100000000
            etfs:
              type: number
              description: ETF market capitalisation (NGN).
              example: 1081200000
            total:
              type: number
              description: Combined market cap (NGN).
              example: 58291047302
        ytd_asi_change_percent:
          type: number
          nullable: true
          description: >-
            ASI percentage change from the first trading day of the current
            year.
          example: 12.37
        turnover_rate:
          type: number
          nullable: true
          description: >-
            Value traded as a percentage of equity market cap. Indicates market
            liquidity.
          example: 0.0093
        breadth:
          type: object
          description: >-
            Market breadth — how many securities advanced, declined, or were
            unchanged in this session.
          properties:
            advancers:
              type: integer
              example: 38
            decliners:
              type: integer
              example: 21
            unchanged:
              type: integer
              example: 14
            total:
              type: integer
              description: Total securities that traded in this session.
              example: 73
            adv_dec_ratio:
              type: number
              nullable: true
              description: Ratio of advancers to decliners. Null when decliners is zero.
              example: 1.81
        total_listed_securities:
          type: integer
          nullable: true
          description: Total number of companies listed on NGX.
          example: 158
        session:
          type: object
          description: NGX trading session times.
          properties:
            open_time:
              type: string
              example: '10:00'
            close_time:
              type: string
              example: '14:30'
            timezone:
              type: string
              example: Africa/Lagos
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
          example: '2026-04-17T18:00:00.000Z'
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error identifier.
              example: NOT_FOUND
            message:
              type: string
              description: Human-readable error description.
              example: Resource not found.
            required_plan:
              type: string
              description: _(PLAN_REQUIRED only)_ Minimum plan needed.
            current_plan:
              type: string
              description: _(PLAN_REQUIRED only)_ Your current plan.
    Meta:
      type: object
      description: Quota and plan metadata included on every authenticated response.
      properties:
        plan:
          type: string
          description: Current plan name.
          enum:
            - free
            - starter
            - growth
            - business
            - enterprise
          example: starter
        calls_used:
          type: integer
          description: Total calls made this calendar month across all your keys.
          example: 4821
        calls_remaining:
          type: integer
          description: Calls remaining before your quota is exhausted.
          example: 95179
        reset_at:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp of your next quota reset (1st of next month).
          example: '2026-05-01T00:00:00.000Z'
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            missingKey:
              summary: Missing Authorization header
              value:
                success: false
                error:
                  code: MISSING_API_KEY
                  message: 'Provide your API key via: Authorization: Bearer <key>'
            invalidKey:
              summary: Invalid or revoked key
              value:
                success: false
                error:
                  code: INVALID_API_KEY
                  message: API key not found or revoked.
    QuotaExceeded:
      description: Monthly call limit reached.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
          example:
            success: false
            error:
              code: QUOTA_EXCEEDED
              message: >-
                Monthly call limit of 100,000 reached. Resets on
                2026-05-01T00:00:00.000Z.
            meta:
              plan: starter
              calls_used: 100000
              calls_remaining: 0
              reset_at: '2026-05-01T00:00:00.000Z'
    ServerError:
      description: Unexpected server-side failure. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: SERVER_ERROR
              message: Something went wrong on our end. Please try again.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ngm_live_*
      description: >
        Pass your API key as a Bearer token: `Authorization: Bearer
        ngm_live_YOUR_KEY`.

        Generate keys at
        [ngnmarket.com/dashboard/developer](https://ngnmarket.com/developer).

````