Open a Hedge

Opening a Hedge is a three-step flow: get a quote to see the cost (optional), submit the open, then poll until it fills. This page walks through all three. For the exact schemas, see POST /hedges in the reference.

1. Get a quote

A quote returns an indicative price and full cost breakdown for a Hedge, without opening anything. Quotes are not binding and not persisted; opening re-prices against the live rate.

curl -X POST "$BASE_URL/quotes" \
  -H "Authorization: Bearer $MARKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"market":"USDTNGN","side":"sell","notional_usd":100000,"tenor_days":7}'

The quote breaks down into three parts:

pricing - execution_price is what the Hedge would open at (mid rate plus impact).
carry - net carry, signed, both daily and over the full tenor.
upfront - total_upfront_usdc is margin plus the open-and-close platform fee, all reserved at open.

2. Open the Hedge

Submit the open with the market, side, size, and tenor. It returns immediately with status: "submitted", an order_tx_hash, and a hedge_id; the position is not live yet.

Field	Type	Required	Description
`market`	string	Yes	e.g. `USDTNGN`.
`side`	string	Yes	`buy` or `sell`.
`notional_usd`	number	Yes	Hedge size in USD, greater than 0.
`tenor_days`	integer	Yes	Settlement tenor. One of `1`, `3`, `7`.
`client_reference`	string	No	Your own deal id, echoed back on the Hedge.

Pass a unique Idempotency-Key header so the open is safe to retry. Retrying with the same key and body returns the original result instead of opening twice. See API Conventions.

curl -X POST "$BASE_URL/hedges" \
  -H "Authorization: Bearer $MARKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"market":"USDTNGN","side":"sell","notional_usd":100000,"tenor_days":7,"client_reference":"deal-4821"}'

The response returns the hedge_id to poll, the collateral_usdc locked at open (margin plus platform fee), the maturity_at date, and a quote echoing the agreed terms.

3. Poll until filled

Poll the Hedge by id until status becomes filled. A filled Hedge gains a fill_tx_hash and its own struck_rate (the rate captured at fill). This usually takes a few seconds.

curl "$BASE_URL/hedges/HEDGE_ID" \
  -H "Authorization: Bearer $MARKS_API_KEY"

If a Hedge ends up failed, nothing was opened and any reserved collateral is released. Re-submit with a new Idempotency-Key.

Once filled, the Hedge is a live position. See Monitor Positions to read its P&L and carry, or Add to a Hedge to grow it.

Getting Started

Concepts

Your Account

Hedge Lifecycle

1. Get a quote

2. Open the Hedge

3. Poll until filled

Next

​1. Get a quote

​2. Open the Hedge

​3. Poll until filled

​Next

1. Get a quote

2. Open the Hedge

3. Poll until filled

Next