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

# Get your plan and current-period credit usage.

> Returns the plan the request was evaluated against and, for requests
authenticated with an API key on `api-pro.dexpaprika.com`, the account
email plus credits used and remaining in the current billing period.

Without an API key (or on the public host, where keys are ignored) the
response carries the plan only; all other fields are omitted.




## OpenAPI

````yaml /api-reference/openapi.yml get /usage
openapi: 3.1.0
info:
  title: DexPaprika API
  version: 1.0.4
  description: >
    # Introduction
      Welcome to the DexPaprika API! This product is developed by [CoinPaprika](https://coinpaprika.com).

      Our API enables developers to query token, pool, and DEX data across multiple blockchain networks. Feel free to explore our endpoints below.

      **Important:** This API is currently in beta and **should not be used in critical solutions or features**, as the service is under active development. We reserve the right to introduce changes or break backward compatibility.

      ---
    # Rate Limits & Monthly Quota
      Two different limits apply, signalled by distinct status codes:

      - **429 Too Many Requests** — you are sending requests too fast (per-minute limit). Slow down and retry after the number of seconds given in the `Retry-After` header.

      - **402 Payment Required** — your monthly credit allowance is exhausted. Retrying will not help; buy a credit pack, enable overage, or upgrade your plan.

      Both codes carry a structured JSON body (`error`, `tier`, `message`, `credits`, and per-scenario fields — see the 402/429 response schemas below). A 402 includes `resets_at`, the UTC timestamp when your allowance rolls over, and deliberately carries no `Retry-After` header.

      Responses include an `X-Api-Plan` header naming the plan the request was evaluated against.

      Call `GET /usage` to check your plan and, when authenticated with an API key on `api-pro.dexpaprika.com`, your current-period credit usage and remaining allowance.

      ---
    # Getting Started

    ## Testing the API - Code Snippets

    The snippets below show how to quickly make a **GET** request. Since this is
    a **public beta** (no API key needed), you can simply call the endpoints
    directly.


    > **Note**: If you see CORS issues in a browser, you may need to call these
    endpoints from a backend server to avoid local browser restrictions.


    ### 1. cURL


    ```bash

    curl -X GET
    "https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10" | jq

    ```

    ### 2. Node.js (JavaScript)

    ```js

    const https = require('https');


    const options = {
      hostname: 'api.dexpaprika.com',
      path: '/networks/ethereum/pools/search?limit=10',
      method: 'GET',
    };


    const req = https.request(options, res => {
      let data = '';
      res.on('data', chunk => { data += chunk; });
      res.on('end', () => { console.log(JSON.parse(data)); });
    });


    req.on('error', error => { console.error(error); });

    req.end();

    ```


    ### 3. Python

    ```python

    import requests


    url = "https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10"


    response = requests.get(url)

    if response.status_code == 200:
        print(response.json())
    else:
        print(f"Error: {response.status_code} -> {response.text}")
    ```

    ### 4. PHP

    ```php

    <?php

    $curl = curl_init();


    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10",
      CURLOPT_RETURNTRANSFER => true
    ));


    $response = curl_exec($curl);


    if(curl_errno($curl)) {
      echo "Error: " . curl_error($curl);
    } else {
      echo $response;
    }


    curl_close($curl);

    ?>

    ```


    ### 5. Java

    ```java

    import java.io.*;

    import java.net.HttpURLConnection;

    import java.net.URL;


    public class DexPaprikaExample {
        public static void main(String[] args) {
            try {
                URL url = new URL("https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10");
                HttpURLConnection con = (HttpURLConnection) url.openConnection();
                con.setRequestMethod("GET");
                int responseCode = con.getResponseCode();
                try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
                    String inputLine;
                    StringBuilder content = new StringBuilder();
                    while ((inputLine = in.readLine()) != null) {
                        content.append(inputLine);
                    }
                    if (responseCode == 200) {
                        System.out.println(content.toString());
                    } else {
                        System.out.println("Error: " + responseCode);
                    }
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }

    ```


    ### 6. Go

    ```go

    package main


    import (
        "fmt"
        "io/ioutil"
        "log"
        "net/http"
    )


    func main() {
        client := &http.Client{}
        req, err := http.NewRequest("GET", "https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10", nil)
        if err != nil {
            log.Fatal(err)
        }

        resp, err := client.Do(req)
        if err != nil {
            log.Fatal(err)
        }
        defer resp.Body.Close()

        body, err := ioutil.ReadAll(resp.Body)
        if err != nil {
            log.Fatal(err)
        }

        if resp.StatusCode == http.StatusOK {
            fmt.Println(string(body))
        } else {
            fmt.Printf("Error: %d -> %s\n", resp.StatusCode, body)
        }
    }

    ```


    ### 7. C#

    ```csharp

    using System;

    using System.Net.Http;

    using System.Threading.Tasks;


    class Program

    {
        static async Task Main()
        {
            using var client = new HttpClient();
            var url = "https://api.dexpaprika.com/networks/ethereum/pools/search?limit=10";
            
            var response = await client.GetAsync(url);
            
            if (response.IsSuccessStatusCode)
            {
                var content = await response.Content.ReadAsStringAsync();
                Console.WriteLine(content);
            }
            else
            {
                Console.WriteLine($"Error: {response.StatusCode}");
            }
        }
    }

    ```


    ## Feedback & Next Steps

    1. **Test** any of the snippets above.  

    2. **Explore** our other endpoints in this documentation.   

    3. **Share** your feedback with us at
    [support@coinpaprika.com](mailto:support@coinpaprika.com).

    4. If you want implement our API into your project or simply discuss
    possible collaboration, please reach out to msroka@coinpaprika.com.

    ---
  contact:
    name: CoinPaprika Support
    email: support@coinpaprika.com
    url: https://coinpaprika.com
  license:
    name: Proprietary
    url: https://dexpaprika.com/terms
servers:
  - url: https://api.dexpaprika.com
    description: Production server
security: []
tags:
  - name: Networks
    description: Endpoints for retrieving information about supported blockchain networks
  - name: DEXes
    description: Endpoints for retrieving information about decentralized exchanges
  - name: Pools
    description: Endpoints for retrieving information about liquidity pools
  - name: Tokens
    description: Endpoints for retrieving information about tokens
  - name: Search
    description: Endpoints for searching across tokens, pools, and DEXes
  - name: Utils
    description: Utility endpoints for system metadata
paths:
  /usage:
    get:
      tags:
        - Utils
      summary: Get your plan and current-period credit usage.
      description: |
        Returns the plan the request was evaluated against and, for requests
        authenticated with an API key on `api-pro.dexpaprika.com`, the account
        email plus credits used and remaining in the current billing period.

        Without an API key (or on the public host, where keys are ignored) the
        response carries the plan only; all other fields are omitted.
      operationId: getUsage
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - plan
                properties:
                  plan:
                    type: string
                    description: >-
                      Plan the request was evaluated against (same value as the
                      `X-Api-Plan` header), e.g. `free`, `pro`, `enterprise`.
                  email:
                    type: string
                    description: >-
                      Account email of the API key owner. Omitted for keyless
                      requests or when no email is on file.
                  requests_used:
                    type: integer
                    description: >-
                      Credits consumed in the current billing period, summed
                      across all of the account's keys. Omitted when not
                      applicable.
                  requests_left:
                    type: integer
                    description: >-
                      Credits remaining in the current billing period, including
                      purchased packs and already-charged overage blocks.
                      Omitted when not applicable.
                  period_started_at:
                    type: string
                    format: date-time
                    description: >-
                      Start of the current billing period (calendar month for
                      free-tier keys). Omitted when not applicable.
                  period_ends_at:
                    type: string
                    format: date-time
                    description: >-
                      End of the current billing period. Omitted when not
                      applicable.
              examples:
                with_key:
                  summary: Authenticated with an API key (api-pro)
                  value:
                    plan: pro
                    email: user@example.com
                    requests_used: 1250000
                    requests_left: 3750000
                    period_started_at: '2026-07-12T00:00:00Z'
                    period_ends_at: '2026-08-12T00:00:00Z'
                without_key:
                  summary: No API key
                  value:
                    plan: free
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    QuotaExceeded:
      description: >
        Monthly credit allowance exhausted. Retrying will not help — the body
        names the available next step per tier: register (keyless), upgrade
        (free key), or buy a credit pack / enable overage / raise your spend cap
        (Pro). `resets_at` is when the allowance rolls over (calendar month or
        billing period, UTC). Deliberately carries no `Retry-After` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuotaErrorBody'
          examples:
            keyless:
              summary: Keyless client over the monthly limit
              value:
                error: payment_required
                tier: keyless
                message: >-
                  Monthly limit reached for unauthenticated use. Register for a
                  free API key to get 300K credits/month.
                credits:
                  limit: 50000
                  used: 50000
                  remaining: 0
                resets_at: '2026-09-01T00:00:00Z'
            pro_plan_exhausted:
              summary: Pro key with plan credits drained, overage off
              value:
                error: payment_required
                tier: pro
                message: >-
                  Monthly credit limit reached — buy a credit pack or enable
                  overage in the portal.
                credits:
                  plan: 5000000
                  packs: 0
                  limit: 5000000
                  used: 5000000
                  remaining: 0
                overage:
                  enabled: false
                resets_at: '2026-09-01T00:00:00Z'
    RateLimited:
      description: >
        Per-minute rate limit exceeded — slow down and retry after the number of
        seconds given in the `Retry-After` header. Credits are unaffected;
        `credits` appears in the body only when the counters were already at
        hand for the request.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuotaErrorBody'
          example:
            error: rate_limited
            tier: pro
            message: Request rate exceeded. Retry in 12 seconds.
            credits:
              plan: 5000000
              packs: 0
              limit: 5000000
              used: 1240880
              remaining: 3759120
            retry_after: 12
  schemas:
    QuotaErrorBody:
      type: object
      description: >
        Structured body carried by every 402 and 429 emitted by the billing
        gate. The shape is constant across scenarios; only fields describing an
        available action appear. `message` is always a top-level string, so
        clients parsing the legacy `{"message": ...}` shape keep working.
      required:
        - error
        - tier
        - message
      properties:
        error:
          type: string
          enum:
            - payment_required
            - rate_limited
          description: Machine-readable discriminator matching the status code.
        tier:
          type: string
          enum:
            - keyless
            - free
            - pro
          description: The billing tier the request was evaluated against.
        message:
          type: string
          description: Human-readable message naming the next action.
        credits:
          type: object
          description: >
            Credit counters for the current period. One credit is one request.
            `plan` and `packs` are split out for Pro keys only. `limit` is plan
            + packs; usage served through overage can exceed it.
          properties:
            plan:
              type: integer
              format: int64
            packs:
              type: integer
              format: int64
            limit:
              type: integer
              format: int64
            used:
              type: integer
              format: int64
            remaining:
              type: integer
              format: int64
        overage:
          type: object
          description: >
            Overage state, present on Pro 402 bodies. Money amounts are decimal
            strings, never floats.
          properties:
            enabled:
              type: boolean
            cap:
              type: string
              example: '200.00'
            used:
              type: string
              example: '200.00'
            block:
              type: string
              example: 20.00 per 1M credits
        resets_at:
          type: string
          format: date-time
          description: When the monthly allowance rolls over (UTC). 402 only.
        retry_after:
          type: integer
          description: Seconds to wait before retrying. 429 only.
        offer:
          type: object
          description: Early-adopter offer, present on the free-tier 402 only.
          properties:
            description:
              type: string
            expires_at:
              type: string
              format: date-time
        links:
          type: object
          additionalProperties:
            type: string
          description: >
            Next-step URLs. Keys vary by scenario: register, upgrade, packs,
            portal, usage, docs. Absent until the customer-facing pages go live.

````