The ELEGG FX API

Getting started

An administrator of the account creates a key in ELEGG FX: Settings → API. One key per software, named after it, so you can revoke one without cutting the others. The key is shown only once; store it in your ERP's secure settings.

Every call carries the key in the Authorization header. Check that it works:

curl https://eleggfinance.com/api/v1/account \
  -H "Authorization: Bearer elegg_live_…"

Common rules

• Base URL: https://eleggfinance.com/api/v1. JSON bodies and responses (UTF-8).
• Every line carries a "reference": the invoice or contract number in your ERP (1 to 100 characters). Sending the same reference again replaces the line instead of duplicating it — so you can resend your whole book every night.
• Your ERP is the source of truth: a resent line also replaces edits made in ELEGG FX, and an optional field left out is cleared.
• All or nothing: if a single line is rejected, nothing is saved and the response lists every error. 1000 lines per call at most.
• The side is never guessed: "buy" when you buy the currency (supplier invoice, imports), "sell" when you sell it (customer invoice, exports).
• Dates as YYYY-MM-DD. Amounts in the line's currency. Rates quoted as currency per 1 euro (EUR/USD 1.0875 is written 1.0875).
• 120 calls per minute per key. Beyond that: 429 response, retry a few seconds later.

Endpoints

Currency needs

A need is an amount of foreign currency to pay or collect: in practice, the amount still due on an invoice. It feeds the exposure, the hedging calendar and the reporting.

curl -X PUT https://eleggfinance.com/api/v1/needs \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "needs": [
      {
        "reference": "FAC-2026-0142",
        "currency": "USD",
        "side": "buy",
        "amount": 125000,
        "due_date": "2026-12-15",
        "counterparty": "Shenzhen Parts Ltd",
        "invoice_number": "SP-88412",
        "budget_rate": 1.08
      }
    ]
  }'

{
  "created": 1,
  "updated": 0,
  "results": [
    { "reference": "FAC-2026-0142", "id": "5f0c…", "status": "created" }
  ]
}

Paid invoices

When an invoice is settled, report it: the need leaves the exposure and joins the payment history. "date" defaults to today; "rate", the rate obtained, is optional. Only needs created through the API can be settled here.

curl -X POST https://eleggfinance.com/api/v1/needs/settlements \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "settlements": [{ "reference": "FAC-2026-0142", "date": "2026-12-14", "rate": 1.0921 }] }'

Hedges

Accepted products: forward, forward_open, ndf, vanilla, tunnel, leveraged, ki_forward. TARFs and accumulators, which expand into one line per fixing, are entered in ELEGG FX by uploading the term sheet.

Product-specific fields are those of manual entry and go through the same checks: a collar needs its cap, a barrier its level, and so on.

curl -X PUT https://eleggfinance.com/api/v1/hedges \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "hedges": [
      {
        "reference": "FWD-2026-031",
        "product_type": "forward",
        "currency": "USD",
        "side": "buy",
        "notional": 500000,
        "rate": 1.0875,
        "maturity_date": "2027-03-31",
        "trade_date": "2026-10-19",
        "counterparty": "BNP Paribas"
      }
    ]
  }'

{
  "valued_at": "2026-10-19T08:12:03.512Z",
  "total_mtm_eur": 3184.52,
  "hedges": [
    {
      "id": "9a71…",
      "reference": "FWD-2026-031",
      "source": "api",
      "product_type": "forward",
      "currency": "USD",
      "side": "buy",
      "notional": 500000,
      "rate": 1.0875,
      "maturity_date": "2027-03-31",
      "mtm_eur": 3184.52,
      …
    }
  ],
  "structures": [],
  "count": 1
}

Reading the MTM

GET /hedges returns every live hedge with "mtm_eur": its market value in euros at the time of the call, computed as on your dashboard. A positive value is in your favour.

"mtm_eur" is null when the hedge cannot be valued (missing market data). TARFs and accumulators are valued as a whole: their value is in "structures", by group_id.

These valuations are negotiation references, not execution prices.

Errors

Every error returns the same object: a stable code to test in your program, and a readable message (in French).

• 400 invalid_body / invalid_parameter — unreadable body or parameter.
• 401 missing_key / invalid_key — key missing, unknown or revoked.
• 403 account_disabled — the account no longer has access to ELEGG FX.
• 404 not_found — no line created through the API under this reference.
• 422 validation_failed — at least one line rejected; "details" lists them all, nothing is written.
• 429 rate_limited — too many calls, retry in a moment.
• 500 internal_error — write to us with the time of the call.

{
  "error": {
    "code": "validation_failed",
    "message": "1 erreur(s) : aucune ligne n'a été enregistrée.",
    "details": [
      { "index": 0, "reference": "FAC-2026-0142", "field": "side",
        "message": "Sens obligatoire : « buy » … ou « sell » …" }
    ]
  }
}