> ## 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. # Request a hedge > A physical contract needs covering. The request becomes a hedge in the Mercora Inbox for an operator to send to the broker; nothing is sent from the API. A request that cannot be planned is still recorded: 201 with `state: failed` and the `reason` (unknown book, no Agiboo position, contract already on another hedge). Scope: `hedge_requests`. ## OpenAPI ````yaml /api-reference/openapi.json post /hedge-requests 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-requests: post: tags: - Hedge requests summary: Request a hedge description: >- A physical contract needs covering. The request becomes a hedge in the Mercora Inbox for an operator to send to the broker; nothing is sent from the API. A request that cannot be planned is still recorded: 201 with `state: failed` and the `reason` (unknown book, no Agiboo position, contract already on another hedge). Scope: `hedge_requests`. operationId: createHedgeRequest requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HedgeRequestCreate' example: external_id: PC-2026-014/2026-10-03T11:00:00Z book: 3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f contract_ref: PC-2026-014 counterparty: Example Cooperative direction: SELL quantity_tonnes: 25 lots: 2 cover_month: 2027-03 requested_by: J. Doe note: Hedge on purchase contract agiboo: position: MAIN FUTURES responses: '200': description: 'Same `external_id`, same body: the hedge already staged.' content: application/json: schema: $ref: '#/components/schemas/HedgeRequest' '201': description: New request staged. Read `state`. content: application/json: schema: $ref: '#/components/schemas/HedgeRequest' example: id: 60d63a3f-d449-4ffa-bb76-78b7b308cfdb external_id: PC-2026-014/2026-10-03T11:00:00Z state: awaiting_approval reason: null plan: book: 3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f commodity: cocoa exchange: LDN direction: SELL lots: 2 futures_symbol: QCH7 cover_month: 2027-03 broker: Example Broker fill: null futures_trade_id: null agiboo: position: MAIN FUTURES created_at: '2026-10-03T10:54:06.092Z' url: >- https:///queue?doc=action:60d63a3f-d449-4ffa-bb76-78b7b308cfdb '400': description: Body is not JSON. content: application/json: schema: $ref: '#/components/schemas/Error' '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' '409': description: Same `external_id`, different body. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Body failed its schema; `issues` lists each field. 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: HedgeRequestCreate: type: object properties: external_id: type: string minLength: 1 maxLength: 200 description: >- Your own id for this request, any string. Sending it again returns the hedge already staged instead of a second one. book: type: string minLength: 1 maxLength: 100 description: >- A book id from GET /hedge-books. It sets the commodity, exchange, futures symbol, lot size and broker. contract_ref: type: string minLength: 1 maxLength: 100 description: >- The physical contract the hedge covers, e.g. "CO25-AC-014". A contract can be on one hedge only. counterparty: type: string minLength: 1 maxLength: 200 description: Supplier or buyer on that contract. direction: type: string enum: - BUY - SELL description: SELL hedges a purchase, BUY hedges a sale. quantity_tonnes: type: number exclusiveMinimum: 0 maximum: 1000000 description: >- Tonnes to hedge: the contract's quantity, or the part of it to cover. lots: type: integer exclusiveMinimum: 0 maximum: 10000 description: >- Lots to trade, when you have decided them; sent to the broker as is. Absent: the tonnes over the book's lot size, rounded to the nearest lot, at least 1. cover_month: type: string pattern: ^(\d{4})-(0[1-9]|1[0-2])$ description: Futures month to cover, as YYYY-MM. requested_by: type: string minLength: 1 maxLength: 200 description: Who asked, in your system. Shown on the Inbox card. note: type: string minLength: 1 maxLength: 2000 description: Shown on the Inbox card. agiboo: type: object properties: position: type: string minLength: 1 maxLength: 100 description: >- The Agiblocks futures position the fill is allocated to: one of GET /hedge-books' `agiboo.positions`. Absent: the book's position. additionalProperties: false description: Only for a workspace that books hedges in Agiboo. required: - external_id - book - contract_ref - counterparty - direction - quantity_tonnes - cover_month additionalProperties: false HedgeRequest: type: object properties: id: type: string description: 'Mercora''s id for the hedge: GET /hedge-requests/{id}.' external_id: type: string description: The caller's own id it was sent with. state: type: string enum: - processing - awaiting_approval - accumulated - merged - sending - awaiting_fill - filled - closed - dismissed - failed description: >- processing: being planned · awaiting_approval: planned, waiting for an operator to send, accumulate or dismiss it · accumulated: parked to go out with a later hedge on the same month · merged: folded into another hedge's order · sending: the broker order is going out · awaiting_fill: order sent, waiting for the broker's fill · filled: fill recorded · closed: closed without a recorded fill · dismissed: an operator dismissed it · failed: could not be planned or sent; `reason` says why reason: type: - string - 'null' description: Why it failed, when `state` is failed. plan: type: - object - 'null' properties: book: type: - string - 'null' description: The book (hedge rule id) it was planned on. commodity: type: string exchange: type: string direction: type: string enum: - BUY - SELL lots: type: number futures_symbol: type: string description: Broker-facing contract symbol, e.g. "QCH7". cover_month: type: - string - 'null' description: >- YYYY-MM, as requested; null if the contract month cannot be read. broker: type: string required: - book - commodity - exchange - direction - lots - futures_symbol - cover_month - broker description: >- The order Mercora planned. Null while processing and when planning failed. fill: type: - object - 'null' properties: lots: type: number price: type: number required: - lots - price description: The broker's fill, once recorded. futures_trade_id: type: - string - 'null' description: The executed trade in Mercora's futures ledger, once filled. agiboo: type: - object - 'null' properties: position: type: string required: - position description: >- Only for a workspace that books hedges in Agiboo; null when the hedge names no Agiboo position. created_at: type: string description: ISO 8601 timestamp. url: type: string description: The hedge in the Mercora Inbox. required: - id - external_id - state - reason - plan - fill - futures_trade_id - agiboo - created_at - url 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.