API Conventions

Everything in the API follows a small set of shared conventions. Read this once and the rest of the reference reads consistently.

Base URL

All endpoints are served over HTTPS and share one base:

https://api.marks.finance/api/v2/partners

Plain HTTP is not supported.

Authentication

Every request carries your API key as a Bearer token. The key prefix selects the environment: mk_live_ for production, mk_test_ for sandbox. The same endpoints serve both. See Authentication for the full details.

Authorization: Bearer mk_live_xxxxxxxx

Response envelope

Every endpoint returns the same envelope:

{ "data": ..., "error": null, "meta": {} }

On success data is populated and error is null. On failure data is null and error carries a machine-readable code, a human-readable message, and optional details. meta carries request context such as the data source. Branch on error.code, not on the message text.

Amounts and rates

Monetary amounts are in USDC unless a field name says otherwise (fields ending in _usd or _usdc). Exchange rates are decimal numbers in quote currency per USDT - a price of 1620.5 on USDTNGN means 1,620.5 naira per USDT. Timestamps are ISO-8601 in UTC.

Asynchronous actions

Opening, adding to, reducing, and closing a Hedge are asynchronous. The call returns status: "submitted" with a transaction hash, and the position settles on-chain shortly after. You poll GET /hedges/{id} (or GET /positions) for the result. There are no webhooks yet.

Idempotency

Opening, adding, reducing, and closing are state-changing, so make them safe to retry with an Idempotency-Key header (any unique string, such as a UUID or your own deal id):

Idempotency-Key: 9f1c2e7a-...

Retrying with the same key and the same body returns the original result instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reuse. A key whose request is still in flight returns 409 idempotency_in_flight. Keys are scoped per environment, so sandbox and production never collide.

Rate limits

Requests are rate limited per API key. If you exceed the limit you get 429 rate_limited; back off and retry. Read endpoints (markets, prices, account, positions) are safe to poll at a steady cadence; there’s no need to poll faster than every second or two.

Errors

Every error response has data: null and a populated error with a stable code, a human-readable message, and optional details. Branch on code. 4xx codes are your request to fix; 5xx codes are transient, so retry with backoff.

{
  "data": null,
  "error": {
    "code": "exposure_exceeded",
    "message": "Total open exposure would exceed your cap.",
    "details": { "available_headroom_usd": 12000 }
  },
  "meta": {}
}

Error codes

Code	HTTP	Meaning
`validation_error`	400	Malformed or missing fields (see `details.fields`)
`market_not_allowed`	400	Market not enabled for your account
`exposure_exceeded`	400	Total open exposure would exceed your cap (see `details.available_headroom_usd`)
`insufficient_collateral`	400	Not enough balance for the requested size
`hedge_not_open`	400	The target Hedge is not open, so it can’t be added to
`account_not_configured`	400	Your partner account has no on-chain account set yet
`missing_credentials`	401	No `Authorization` header
`invalid_api_key`	401	API key not found or revoked
`insufficient_scope`	403	API key lacks the required scope
`account_forbidden`	403	The requested account is not yours
`hedge_not_found`	404	No Hedge with that id on your account
`no_open_hedge`	404	No open Hedge on that market and side to add to (open one instead)
`hedge_exists`	409	You already have an open Hedge on that market and side; add to it or settle it first
`idempotency_in_flight`	409	A request with this `Idempotency-Key` is still processing
`idempotency_key_reuse`	409	`Idempotency-Key` reused with a different request body
`rate_limited`	429	Too many requests
`quote_failed`	502	Could not build a quote
`execution_failed`	502	The order could not be submitted
`onchain_read_failed`	502	Could not read market or account data
`price_unavailable`	503	Price feed temporarily unavailable
`executor_unavailable`	503	Execution service temporarily unavailable
`service_unavailable`	503	A required service is temporarily unavailable

Getting Started

Concepts

Your Account

Hedge Lifecycle

Base URL

Authentication

Response envelope

Amounts and rates

Asynchronous actions

Idempotency

Rate limits

Errors

Error codes

​Base URL

​Authentication

​Response envelope

​Amounts and rates

​Asynchronous actions

​Idempotency

​Rate limits

​Errors

​Error codes

Base URL

Authentication

Response envelope

Amounts and rates

Asynchronous actions

Idempotency

Rate limits

Errors

Error codes