Request a hedge

POST

hedge-requests

Request a hedge

curl --request POST \
  --url https://{workspace}.mercora.io/api/v1/hedge-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://{workspace}.mercora.io/api/v1/hedge-requests"

payload = {
    "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" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://{workspace}.mercora.io/api/v1/hedge-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{workspace}.mercora.io/api/v1/hedge-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{workspace}.mercora.io/api/v1/hedge-requests"

	payload := strings.NewReader("{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{workspace}.mercora.io/api/v1/hedge-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{workspace}.mercora.io/api/v1/hedge-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "external_id": "<string>",
  "state": "processing",
  "reason": "<string>",
  "plan": {
    "book": "<string>",
    "commodity": "<string>",
    "exchange": "<string>",
    "direction": "BUY",
    "lots": 123,
    "futures_symbol": "<string>",
    "cover_month": "<string>",
    "broker": "<string>"
  },
  "fill": {
    "lots": 123,
    "price": 123
  },
  "futures_trade_id": "<string>",
  "agiboo": {
    "position": "<string>"
  },
  "created_at": "<string>",
  "url": "<string>"
}

{
  "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://<workspace>/queue?doc=action:60d63a3f-d449-4ffa-bb76-78b7b308cfdb"
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

A workspace API key (mk_…), made under Settings → Administration → API.

Body

application/json

external_id

string

required

Your own id for this request, any string. Sending it again returns the hedge already staged instead of a second one.

Required string length: 1 - 200

book

string

required

A book id from GET /hedge-books. It sets the commodity, exchange, futures symbol, lot size and broker.

Required string length: 1 - 100

contract_ref

string

required

The physical contract the hedge covers, e.g. "CO25-AC-014". A contract can be on one hedge only.

Required string length: 1 - 100

counterparty

string

required

Supplier or buyer on that contract.

Required string length: 1 - 200

direction

enum<string>

required

SELL hedges a purchase, BUY hedges a sale.

Available options:

BUY,

SELL

quantity_tonnes

number

required

Tonnes to hedge: the contract's quantity, or the part of it to cover.

Required range: x <= 1000000

cover_month

string

required

Futures month to cover, as YYYY-MM.

Pattern: ^(\d{4})-(0[1-9]|1[0-2])$

lots

integer

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.

Required range: x <= 10000

requested_by

string

Who asked, in your system. Shown on the Inbox card.

Required string length: 1 - 200

note

string

Shown on the Inbox card.

Required string length: 1 - 2000

agiboo

object

Only for a workspace that books hedges in Agiboo.

Show child attributes

Response

Same external_id, same body: the hedge already staged.

string

required

Mercora's id for the hedge: GET /hedge-requests/{id}.

external_id

string

required

The caller's own id it was sent with.

state

enum<string>

required

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

Available options:

processing,

awaiting_approval,

accumulated,

merged,

sending,

awaiting_fill,

filled,

closed,

dismissed,

failed

reason

string | null

required

Why it failed, when state is failed.

plan

object | null

required

The order Mercora planned. Null while processing and when planning failed.

Show child attributes

fill

object | null

required

The broker's fill, once recorded.

Show child attributes

futures_trade_id

string | null

required

The executed trade in Mercora's futures ledger, once filled.

agiboo

object | null

required

Only for a workspace that books hedges in Agiboo; null when the hedge names no Agiboo position.

Show child attributes

created_at

string

required

ISO 8601 timestamp.

url

string

required

The hedge in the Mercora Inbox.

⌘I

Request a hedge

curl --request POST \
  --url https://{workspace}.mercora.io/api/v1/hedge-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://{workspace}.mercora.io/api/v1/hedge-requests"

payload = {
    "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" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://{workspace}.mercora.io/api/v1/hedge-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{workspace}.mercora.io/api/v1/hedge-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{workspace}.mercora.io/api/v1/hedge-requests"

	payload := strings.NewReader("{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{workspace}.mercora.io/api/v1/hedge-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{workspace}.mercora.io/api/v1/hedge-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_id\": \"PC-2026-014/2026-10-03T11:00:00Z\",\n  \"book\": \"3f2a9c41-7b1e-4c55-9d0e-1a2b3c4d5e6f\",\n  \"contract_ref\": \"PC-2026-014\",\n  \"counterparty\": \"Example Cooperative\",\n  \"direction\": \"SELL\",\n  \"quantity_tonnes\": 25,\n  \"lots\": 2,\n  \"cover_month\": \"2027-03\",\n  \"requested_by\": \"J. Doe\",\n  \"note\": \"Hedge on purchase contract\",\n  \"agiboo\": {\n    \"position\": \"MAIN FUTURES\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "external_id": "<string>",
  "state": "processing",
  "reason": "<string>",
  "plan": {
    "book": "<string>",
    "commodity": "<string>",
    "exchange": "<string>",
    "direction": "BUY",
    "lots": 123,
    "futures_symbol": "<string>",
    "cover_month": "<string>",
    "broker": "<string>"
  },
  "fill": {
    "lots": 123,
    "price": 123
  },
  "futures_trade_id": "<string>",
  "agiboo": {
    "position": "<string>"
  },
  "created_at": "<string>",
  "url": "<string>"
}

{
  "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://<workspace>/queue?doc=action:60d63a3f-d449-4ffa-bb76-78b7b308cfdb"
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "error": "<string>",
  "issues": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Overview

Hedging

Automations

Request a hedge

Authorizations

Body

Response