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

# Get Market Rate

Returns **buy** and **sell** market rate **bands** (reference rate plus min/max tolerance) for a token/fiat pair. Use this to validate whether a sender-provided `rate` on order creation is within allowed bounds.

## Response shape (`data`)

| Field  | Type              | Description                       |
| ------ | ----------------- | --------------------------------- |
| `buy`  | object (optional) | Buy-side band — see fields below  |
| `sell` | object (optional) | Sell-side band — see fields below |

Each side object:

| Field         | Type              | Description                                           |
| ------------- | ----------------- | ----------------------------------------------------- |
| `marketRate`  | string            | Reference market rate for this side (fiat per crypto) |
| `minimumRate` | string            | Minimum allowed rate for this side                    |
| `maximumRate` | string            | Maximum allowed rate for this side                    |
| `position`    | object (optional) | Rate benchmark vs. best public peer — see below       |

Numeric values are returned as **strings** (decimal). Either side may be omitted depending on corridor configuration.

## `position` object

When qualifying public offers exist for this corridor, each side includes a `position` object so you can see how your effective rate compares to the best public peer:

| Field               | Type   | Description                                                                         |
| ------------------- | ------ | ----------------------------------------------------------------------------------- |
| `bestPublicRate`    | string | Best rate among enabled non-testnet public peers (highest for sell; lowest for buy) |
| `yourEffectiveRate` | string | Your own effective rate for this corridor and side                                  |
| `deltaVsBest`       | string | `yourEffectiveRate − bestPublicRate`                                                |

**Interpreting `deltaVsBest`:**

* **Sell** (offramp): a **positive** delta means your rate is higher than the best peer — you are more competitive.
* **Buy** (onramp): a **negative** delta means your rate is lower than the best peer — you are more competitive.

`position` is **omitted** when:

* No qualifying public offers exist for the corridor, or
* You have no effective rate configured for this corridor.

The reference fields `marketRate`, `minimumRate`, and `maximumRate` are **unchanged** — `position` is purely additive (backward compatible).

The benchmark pool uses all enabled, non-testnet networks; it is not filtered by the `{token}/{fiat}` path parameters' network.

## Example

```json theme={null}
{
  "status": "success",
  "message": "Rate fetched successfully",
  "data": {
    "sell": {
      "marketRate": "1605.00",
      "minimumRate": "1580.00",
      "maximumRate": "1630.00",
      "position": {
        "bestPublicRate": "1608.00",
        "yourEffectiveRate": "1605.00",
        "deltaVsBest": "-3.00"
      }
    },
    "buy": {
      "marketRate": "1598.00",
      "minimumRate": "1575.00",
      "maximumRate": "1620.00",
      "position": {
        "bestPublicRate": "1595.00",
        "yourEffectiveRate": "1598.00",
        "deltaVsBest": "3.00"
      }
    }
  }
}
```

Example when `position` is omitted (no public benchmark available):

```json theme={null}
{
  "status": "success",
  "message": "Rate fetched successfully",
  "data": {
    "sell": {
      "marketRate": "1605.00",
      "minimumRate": "1580.00",
      "maximumRate": "1630.00"
    }
  }
}
```

<Note>
  **`GET /v1/provider/rates/{token}/{fiat}`** uses the same response shape as this v2 route, including the `position` field. See [Get Market Rate (v1)](/api-reference/provider/get-market-rate-v1).
</Note>


## OpenAPI

````yaml openapi-v2.yaml GET /provider/rates/{token}/{fiat}
openapi: 3.0.3
info:
  title: Paycrest Aggregator API
  version: 1.0.0
  description: >
    OpenAPI schema for the Paycrest Aggregator API. This covers sender,
    provider, and general endpoints.
servers:
  - url: https://api.paycrest.io/v2
security: []
tags:
  - name: Sender
    description: Endpoints for senders to create and manage payment orders
  - name: Provider
    description: Endpoints for providers to manage and fulfill orders
  - name: General
    description: General protocol and utility endpoints
paths:
  /provider/rates/{token}/{fiat}:
    get:
      tags:
        - Provider
      summary: Get market rate
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
        - in: path
          name: fiat
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Market rate
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StandardResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/MarketRateResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuth: []
      servers:
        - url: https://api.paycrest.io/v2
components:
  schemas:
    StandardResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Operation successful
        data:
          type: object
          description: The actual response data (e.g., ReceiveAddressResponse, etc.)
    MarketRateResponse:
      type: object
      description: >-
        Market rate bounds split by side. Either or both of `buy` and `sell` may
        be present depending on corridor configuration.
      properties:
        buy:
          $ref: '#/components/schemas/MarketRateSide'
        sell:
          $ref: '#/components/schemas/MarketRateSide'
    MarketRateSide:
      type: object
      description: Tolerance band for one side (buy or sell) of the market rate.
      properties:
        marketRate:
          type: string
          description: Reference market rate for this side (fiat per crypto).
        minimumRate:
          type: string
          description: Minimum allowed rate for this side.
        maximumRate:
          type: string
          description: Maximum allowed rate for this side.
        position:
          allOf:
            - $ref: '#/components/schemas/MarketPosition'
          description: >-
            Rate benchmark vs. best public peer. Omitted when no public
            benchmark exists (backward compatible).
    MarketPosition:
      type: object
      description: >
        Provider's rate standing versus the best public peer in the same
        corridor.

        Omitted when no qualifying public offers exist or the provider has no
        effective rate for the corridor (backward compatible).
      properties:
        bestPublicRate:
          type: string
          description: >-
            Best rate among enabled non-testnet public peers for this side
            (highest effective sell rate; lowest effective buy rate).
        yourEffectiveRate:
          type: string
          description: The provider's own effective rate for this corridor and side.
        deltaVsBest:
          type: string
          description: >
            `yourEffectiveRate − bestPublicRate`. For **sell** a positive delta
            means you offer a higher rate than the best peer (more competitive).
            For **buy** a negative delta means you offer a lower rate than the
            best peer (more competitive).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: API-Key

````