Introduction

Call Mercora from your own systems: base URL, authentication, scopes, errors and idempotency.

The Mercora API lets your own systems, such as an ERP or an internal script, work with your workspace. It covers two areas:

• Hedging: read your hedge books and positions, send hedge requests, and check where they stand.
• Automations: start runs of automations set to run from the API, and hand a waiting run what it’s waiting for.

Whatever a call creates lands in the Inbox for a person on your team to decide on. A hedge request isn’t sent to your broker until someone sends it from the Inbox, and anything an automation run would change waits for a person. This page covers what every call has in common; the endpoint pages list every field and response.

You need a workspace API key with the right scope. A workspace admin creates one under Settings → API. See API keys.

Base URL and authentication

https://{workspace}.mercora.io/api/v1

Replace {workspace} with your workspace’s subdomain; the exact base URL is under Settings → API → Connection. Requests and responses use JSON.

Send the key as a Bearer token on every request:

curl https://{workspace}.mercora.io/api/v1/hedge-books \
  -H "Authorization: Bearer mk_your_api_key"

The key alone decides which workspace you’re calling; you never send a workspace ID.

Call the API from your servers, never from a browser or mobile app. Anyone with a key can call Mercora as your workspace, within its scopes.

Scopes

Each endpoint needs one scope. A key without it gets a 403.

Scope	Endpoints
hedge_requests	GET /hedge-books, POST /hedge-requests, GET /hedge-requests/{id}
automations	POST /agents/{id}/run, POST /agents/{id}/runs/{runId}/callback

POST /hedge-requests also needs the Hedging module, and both automation endpoints need the Automations module. While the module is off, those calls return 403. See Modules.

Errors

Request bodies have a fixed schema: unknown fields are refused, so a misspelled field fails with a 422 instead of being ignored. Errors always come back as JSON with an error message; a 422 also lists each problem in issues:

{
  "error": "Invalid hedge request.",
  "issues": [
    { "field": "book", "message": "Required" }
  ]
}

field is the path to the field that failed, or null when the problem isn’t tied to one field.

Status	Meaning
200	Success, or a repeated create: see Idempotency.
201	Created.
202	An automation run’s callback was received and the run carries on.
400	The body isn’t valid JSON.
401	The API key is missing, malformed, unknown or revoked.
403	The key lacks the endpoint’s scope, or the module it needs is off.
404	No such object in your workspace.
409	Usually an external_id reused with a different body. For automations, also an automation not set to run from the API, or a run that isn’t waiting for a callback.
422	The body failed validation. See issues.
429	Automations only: your workspace’s daily automation-run budget is used up. It resets at midnight UTC.
500	Something went wrong on Mercora’s side. It’s safe to retry with the same external_id.

Idempotency

POST /hedge-requests and POST /agents/{id}/run take your own external_id: any string up to 200 characters that identifies the request in your system, such as a purchase order number.

• Same external_id, same body: Mercora returns what it created the first time, with 200 instead of 201. If you lose a response, for example on a timeout, just send the request again.
• Same external_id, different body: 409. Use a new external_id for a new request.

Mercora issues an id for every object it creates; read objects back by it, for example GET /hedge-requests/{id}. If you lose a hedge request’s id, resend the original POST with the same external_id to get it back.

OpenAPI

The endpoint pages are generated from Mercora’s OpenAPI 3.1 document. A workspace admin can also open the interactive reference (Swagger UI) and download openapi.json from Settings → API.