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

# List hedge books

> What this workspace can hedge: its active hedge rules, each with the `id` a request sends as `book`. On a workspace that books hedges in Agiboo, also each book's position and every position a request may name.

Scope: `hedge_requests`.



## OpenAPI

````yaml /api-reference/openapi.json get /hedge-books
openapi: 3.1.0
info:
  title: Mercora API
  version: v1
  description: >-
    Your own systems call Mercora with a workspace API key. Bodies are JSON with
    a fixed schema; unknown fields are refused. Errors are `{ error }`, plus
    `issues` on a 422. A create carries your own `external_id`: sending it again
    returns what was created the first time.
servers:
  - url: https://{workspace}.mercora.io/api/v1
    description: Your Mercora workspace
    variables:
      workspace:
        default: your-company
        description: Your workspace subdomain
security: []
tags:
  - name: Hedge requests
    description: >-
      Read the hedge books and positions, push hedge requests into the Inbox,
      read where they stand.
  - name: Automations
    description: >-
      Start runs of automations set to run from the API. What a run would change
      still waits for a person in Mercora.
paths:
  /hedge-books:
    get:
      tags:
        - Hedge requests
      summary: List hedge books
      description: >-
        What this workspace can hedge: its active hedge rules, each with the
        `id` a request sends as `book`. On a workspace that books hedges in
        Agiboo, also each book's position and every position a request may name.


        Scope: `hedge_requests`.
      operationId: listHedgeBooks
      responses:
        '200':
          description: The workspace's books.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HedgeBooks'
              example:
                books:
                  - id: 3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f
                    keyword: '*'
                    commodity: cocoa
                    exchange: LDN
                    currency: GBP
                    tonnes_per_lot: 10
                    broker: Example Broker
                    agiboo:
                      position: MAIN FUTURES
                agiboo:
                  positions:
                    - MAIN FUTURES
        '401':
          description: Key missing, unknown or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The key lacks the `hedge_requests` scope, or the resource's module
            is off for the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Ours, logged with the workspace and key. Retrying is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    HedgeBooks:
      type: object
      properties:
        books:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Send as `book` in a hedge request.
              keyword:
                type: string
                description: >-
                  The rule's keyword, to recognise the book by. A WhatsApp
                  confirmation is matched to it by counterparty; "*" catches
                  any.
              commodity:
                type: string
              exchange:
                type: string
              currency:
                type: string
              tonnes_per_lot:
                type: number
              broker:
                type: string
              agiboo:
                type: object
                properties:
                  position:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Where this book's fills are allocated. Null: a request
                      must name one.
                required:
                  - position
                description: Only on a workspace that books hedges in Agiboo.
            required:
              - id
              - keyword
              - commodity
              - exchange
              - currency
              - tonnes_per_lot
              - broker
        agiboo:
          type: object
          properties:
            positions:
              type: array
              items:
                type: string
              description: Every position a request's `agiboo.position` may name.
          required:
            - positions
          description: Only on a workspace that books hedges in Agiboo.
      required:
        - books
    Error:
      type: object
      properties:
        error:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              field:
                type:
                  - string
                  - 'null'
              message:
                type: string
            required:
              - field
              - message
          description: 'On a 422: one entry per field that failed.'
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A workspace API key (mk_…), made under Settings → Administration → API.

````

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