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

# Get Orderbook

> Returns the latest cached on-chain orderbook for all configured token pairs.
The cache refreshes on every new block via `eth_subscribe`, so the data always
reflects the most recent chain state.

Each pair has a `baseToken` (non-USDC token, e.g. WETH) and a `quoteToken` (USDC).
Prices are expressed as **USDC per base token** (decimal strings).
Amounts are **human-readable base token quantities** (decimal strings).

Levels are **marginal** — each level is an independent price point, not cumulative depth.
`bids` are sorted descending (best bid first); `asks` are sorted ascending (best ask first).


Returns the live on-chain orderbook for all configured token pairs. The cache is refreshed on every new block via `eth_subscribe`, so the response always reflects the most recent chain state.

Use this endpoint to get current market prices before executing a swap, or to display market depth to users.

## Understanding the Orderbook

* **bids** — prices at which PropAMM will **buy** the base token (you sell base, receive USDC). Sorted **descending**.
* **asks** — prices at which PropAMM will **sell** the base token (you buy base, pay USDC). Sorted **ascending**.
* Each level is **marginal** — independent price points, not cumulative depth.
* Prices and amounts are **decimal strings** to preserve EVM-scale precision.

If the cache has not been populated yet (service just started), `pairs` may be empty.

## Alternative: On-chain Quote

For a precise quote for a specific input amount, use the on-chain `quote()` function with an EIP-712 signature. See the [Integration Guide](/index#getting-a-quote).

***

## Response Fields

### Top-level

| Field         | Type    | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| `blockNumber` | integer | Block at which the orderbook was last refreshed |
| `blockTime`   | integer | Unix timestamp (seconds) of that block          |
| `pairs`       | array   | One entry per configured token/USDC pair        |

### `pairs[].PairOrderbook`

| Field        | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| `baseToken`  | string | EVM address of the non-USDC token (e.g. WETH) |
| `quoteToken` | string | EVM address of the USDC token                 |
| `bids`       | array  | Buy-side levels, sorted by descending price   |
| `asks`       | array  | Sell-side levels, sorted by ascending price   |

### `bids[].OrderbookLevel` / `asks[].OrderbookLevel`

| Field    | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| `price`  | string | USDC per token, decimal string (e.g. `"3200.50"`) |
| `amount` | string | Token quantity, decimal string (e.g. `"1.5"`)     |


## OpenAPI

````yaml get /v1/price
openapi: 3.0.3
info:
  title: Kipseli PropAMM
  version: 1.0.0
  description: |
    HTTP service that signs PropAMM quote payloads for EVM verification flows
    and serves a live on-chain orderbook for configured token pairs.
  license:
    name: MIT
servers:
  - url: https://propamm.kipseli.win
    description: Production
security: []
paths:
  /v1/price:
    get:
      summary: Get live orderbook
      description: >
        Returns the latest cached on-chain orderbook for all configured token
        pairs.

        The cache refreshes on every new block via `eth_subscribe`, so the data
        always

        reflects the most recent chain state.


        Each pair has a `baseToken` (non-USDC token, e.g. WETH) and a
        `quoteToken` (USDC).

        Prices are expressed as **USDC per base token** (decimal strings).

        Amounts are **human-readable base token quantities** (decimal strings).


        Levels are **marginal** — each level is an independent price point, not
        cumulative depth.

        `bids` are sorted descending (best bid first); `asks` are sorted
        ascending (best ask first).
      operationId: getPrice
      responses:
        '200':
          description: Current orderbook snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceResponse'
              examples:
                weth_cbbtc:
                  summary: Two pairs — WETH/USDC and cbBTC/USDC
                  value:
                    blockNumber: 29500000
                    blockTime: 1741737600
                    pairs:
                      - baseToken: '0x4200000000000000000000000000000000000006'
                        quoteToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        bids:
                          - price: '3200.50'
                            amount: '1.0'
                          - price: '3198.00'
                            amount: '5.0'
                          - price: '3190.25'
                            amount: '10.0'
                        asks:
                          - price: '3201.75'
                            amount: '1.0'
                          - price: '3204.00'
                            amount: '5.0'
                          - price: '3210.50'
                            amount: '10.0'
                      - baseToken: '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf'
                        quoteToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        bids:
                          - price: '97500.00'
                            amount: '0.01'
                          - price: '97200.00'
                            amount: '0.05'
                        asks:
                          - price: '97600.00'
                            amount: '0.01'
                          - price: '97900.00'
                            amount: '0.05'
                empty_cache:
                  summary: Cache not yet populated (service just started)
                  value:
                    blockNumber: 0
                    blockTime: 0
                    pairs: []
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: internal server error
                  requestId: abc-123
      security: []
components:
  schemas:
    PriceResponse:
      type: object
      properties:
        blockNumber:
          type: integer
          format: int64
          description: >
            The on-chain block number at which the orderbook was last refreshed.

            Updates on every new block. Zero if the cache has not been populated
            yet.
          example: 29500000
        blockTime:
          type: integer
          format: int64
          description: |
            Unix timestamp (seconds) of the block identified by `blockNumber`.
            Zero if the cache has not been populated yet.
          example: 1741737600
        pairs:
          type: array
          description: >
            Orderbook for each configured token/USDC pair. Empty if the cache
            has

            not been populated yet (e.g. service just started).
          items:
            $ref: '#/components/schemas/PairOrderbook'
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    PairOrderbook:
      type: object
      description: Full bid/ask orderbook for one base token / USDC pair
      properties:
        baseToken:
          type: string
          description: |
            EVM hex address of the non-USDC token (e.g. WETH, cbBTC).
            This is the token whose price is quoted in USDC.
          example: '0x4200000000000000000000000000000000000006'
        quoteToken:
          type: string
          description: EVM hex address of the USDC token used as the price denomination
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        bids:
          type: array
          description: >
            Buy-side levels — prices at which the AMM will buy the base token
            (you sell base, receive USDC).

            Sorted by **descending** price (best bid first).
          items:
            $ref: '#/components/schemas/OrderbookLevel'
        asks:
          type: array
          description: >
            Sell-side levels — prices at which the AMM will sell the base token
            (you buy base, pay USDC).

            Sorted by **ascending** price (best ask first).
          items:
            $ref: '#/components/schemas/OrderbookLevel'
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - INVALID_JSON
            - VALIDATION_ERROR
            - UNSUPPORTED_FIELD
            - SIGNING_FAILED
            - ENCODING_FAILED
            - INTERNAL_ERROR
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: 'tokenIn: invalid EVM address'
        requestId:
          type: string
          description: Request ID for correlation with server logs
          example: abc-123
    OrderbookLevel:
      type: object
      description: A single marginal price/amount level in the orderbook
      properties:
        price:
          type: string
          description: >
            USDC per base token as a decimal string. Returned as a string (not a
            float)

            to preserve precision for EVM-scale values.
          example: '3200.50'
        amount:
          type: string
          description: >
            Human-readable base token quantity available at this price level, as
            a decimal string.

            This is the marginal amount at this specific price point, not
            cumulative depth.
          example: '1.0'

````