Quickstart

Open your first Hedge in a few minutes: quote, open, poll, and close.

This walks through the full Hedge lifecycle end to end - checking a market, pricing a Hedge, opening it, watching it fill, and closing it. Run it against the sandbox with a mk_test_ key, then switch to a mk_live_ key when you’re ready.

Prerequisites

Create a key in Settings on the partner desk, then export it and the base URL. Use a mk_test_ key to run this against the sandbox with test funds.

export BASE_URL="https://api.marks.finance/api/v2/partners"
export MARKS_API_KEY="mk_test_xxxxxxxx"

See API Conventions for authentication, the response envelope, idempotency, and error handling.

1. Check the market

Fetch the markets available to you. Each one shows its current rate, the capacity you can open per side, and the daily carry rate.

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

2. Price the Hedge

Request an indicative quote for a market, side, size, and tenor. The quote returns the execution price, carry over the tenor, and the upfront cost (margin plus platform fee). Nothing is opened or persisted.

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}'

3. Open the Hedge

Opening is asynchronous. The call returns immediately with status: "submitted", an order_tx_hash, and a hedge_id; the position fills shortly after. Pass a unique Idempotency-Key so the open is safe to retry, and an optional client_reference to tag the Hedge with your own deal id.

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 includes a hedge_id. Save it - you’ll poll it next.

4. Poll until filled

Poll the Hedge until status becomes filled (it also gains a fill_tx_hash and a struck_rate). This usually takes a few seconds.

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

Poll every second or two. A Hedge moves submitted to filled once the on-chain order lands. If it ends up failed, nothing was opened and any reserved collateral is released.

5. Check your position

Once filled, your live position shows up with its mark price, P&L, and accrued carry.

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

6. Close the Hedge

Close the position by market and side. Closing fills the same asynchronous way; GET /positions returns to flat once it drains.

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

Next steps

How Hedging Works

NDFs, tenor, carry, margin, and settlement.

Open a Hedge

The open flow in full, with every field.

Monitor Positions

Read P&L, carry, and margin on a live Hedge.

API Reference

Every endpoint, with request and response schemas.