Concepts

Concepts

Five concepts every Crebit Lock integration depends on. Read these once, then refer back to the schemas on API endpoints.

Lock window

The lock window is the time range during which your customer may execute at the locked rate. Two ISO-8601 UTC datetimes define it:

• window_start, the first moment the customer is allowed to transact at the locked rate.
• window_end, the last moment the customer is allowed to transact at the locked rate.

The customer may transact at any moment in [window_start, window_end]. The locked rate is identical at every moment in the window , only the moment the customer picks varies. You set both fields on the quote; the contract inherits them and they're immutable for the life of the lock. Windows can be as short as a few minutes or as long as 180 days.

How long can a window be?

Anywhere from 1 hour (the minimum lock duration) out to 180 days ahead. Two hard rules:

• window_end > window_start, no equal values.
• window_end must be at least 1 hour after the current time, so the lock window lasts at least 1 hour from when you submit the quote.

Longer windows cost more premium because the customer holds more optionality (more days to pick a favourable market move).

Fields & rules

Lock window

Every quote defines a calendar window during which the customer can execute the locked rate. Always send window_start and window_end:

• Both window_start and window_end are required on every quote.
• window_end must be STRICTLY AFTER window_start, equal values are rejected with validation_error.
• window_end must be at least 1 hour AFTER the current time, meaning the lock window has to last at least 1 hour from when the quote is created. Crebit needs that hour of hedging runway. Anything shorter is rejected with validation_error.
• Maximum window: window_end must be within 180 days of now.
• The customer may execute at any moment within [window_start, window_end], the locked rate is identical at every moment in the window.
• Window length affects pricing, longer windows cost more premium (the customer holds more optionality).
• Both contract_type values (forward, option) accept the same window fields.

Concrete examples

Currencies in a quote

Every quote has two currency-related decisions: which FX pair (and which side of it the customer is fixing) and which stablecoin Crebit settles in with you.

Supported directions

We support hedging USD against BRL, MXN, and EUR. Hedging can be done both ways, from USD to the target currency, or the target currency to USD. There are six values for direction:

USD_TO_BRL · BRL_TO_USD · USD_TO_MXN · MXN_TO_USD · USD_TO_EUR · EUR_TO_USD

direction only fixes the FX pair AND which side the trade flows from. Which side of the pair the customer is fixing their amounton, the amount they're sending or the amount they want to receive, is set independently via notional_currency below.

The three fields you send for the currency setup

Supported chains

Supported stablecoins

Rules

• One stablecoin per contract - settlement_currency covers both the partner funding leg and the customer payout leg.
• Webhook values must match the contract - currency on funds_in_route must equal the contract's settlement_currency; same for chain. Mismatches return 409 contract_mismatch.
• Pricing reflects on-chain settlement cost, Ethereum quotes are higher than Polygon all else equal.

Strike, spot, and market rate

Every quote response carries three rates that a partner often confuses. Knowing the difference lets you message your customer accurately, and tells you whether a CIP-fair forward gives them a strike better than today's market (which happens more often than people think).

Three rates that matter

Three strike modes

On every quote you choose strike_mode. Omit it and Crebit defaults to cip_fair.

How CIP-fair works

Covered interest parity (CIP) says a forward FX rate equals spot adjusted by the interest-rate differential between the two currencies, so the no-arbitrage forward is F = S × (1 + r_quote × t) / (1 + r_notional × t). Crebit applies this from market_rate for the length of the lock window.

strike_advantage_bps explained

The single number you use to tell your customer if the lock is a good deal. Direction-aware, positive always means "customer wins", regardless of which way the FX is going or which strike_mode produced it. Expressed in basis points.

Which mode to pick

Crebit prices to whatever mode + strike you specify. Aggressive strikes flow through to a higher premium_amount.

Forward vs option

contract_type picks one of two shapes: forward or option. It's orthogonal to strike_mode, you can combine forwards or options with any of the three strike modes.

The two dimensions combine cleanly. Six common combinations:

Idempotency

Send Idempotency-Key (UUID recommended) on every write. Same key + same body returns the original response within TTL, so retries are safe.

• POST /api/v1/fx/quotes, recommended.
• POST /api/v1/fx/contracts, recommended.
• POST /api/v1/fx/webhooks/inbound, required (8–256 chars).
• Outbound webhooks (Crebit → you): use the event_id field as your idempotency key. Crebit may retry the same delivery if your endpoint returns a non-2xx within 10s.

Errors

All errors return a JSON envelope:

{
  "code": "validation_error",
  "message": "window_end must be after window_start",
  "details": {}
}

Common code values: