Introduction

What is a rate lock?

A rate lock is a binding promise from Crebit to honor a specific FX rate for your customer over a calendar window. If the market moves against the customer, Crebit absorbs the difference and pays them the delta in a stablecoin. If the market moves their way, they transact at the better live rate and Crebit owes nothing.

Crebit Lock is the API your platform calls to offer this protection without taking on the FX risk yourself.

The flow

What happens, step by step

YouAsk for a price

You tell Crebit your customer wants to lock an FX rate for some window of time.

You describe the trade (which currencies, how much, what date range). Crebit prices the lock and returns the rate we'll guarantee.

YouLock it in

Customer accepts the quote. You convert it into a binding contract.

You confirm the customer wants the lock. Crebit commits to the rate for the entire window, immutable once locked.

CustomerCustomer transacts

Customer does their FX trade on your platform at the live spot rate, like normal.

The customer pays / receives at your live rate on the day they transact, the lock doesn't change what they pay you. It just promises Crebit will cover the difference if the market moved unfavourably since the lock.

YouTell Crebit it happened

You let Crebit know the customer transacted, at what rate, and where to send the refund.

You send a webhook with the live rate and the customer's wallet address. Crebit uses these to compute the refund owed.

CrebitCrebit pays your customer

Crebit sends the FX difference on-chain directly to your customer's wallet.

Crebit calculates the difference between the locked rate and the live rate, converts it to your customer's preferred stablecoin, and sends it on-chain to their wallet. You get a webhook confirming the transaction settled.

That's the whole story. For the exact HTTP calls and field schemas, see API endpoints , or jump straight to the Quickstart.

What you handle vs. Crebit

You handle	Crebit handles
Customer UX, KYC, consent	Pricing the lock
Sending the upfront fee on-chain	Hedging the FX risk behind the lock so the locked rate stays guaranteed
Webhook when the customer transacts	Computing & sending the on-chain payout
Receiving the confirmation webhook	Sending the confirmation webhook with the on-chain tx hash

Auth & environments

Three headers on every call. Crebit provisions sandbox and production keys during onboarding.

Header	Example
X-Crebit-Key-Id	cbk_sbx_…
X-Crebit-Key-Secret	cbs_…
X-Crebit-Environment	sandbox or production

Environment	Base URL
Sandbox	https://lock-apis-test.crebitpay.com
Production	https://lock-apis.crebitpay.com

Verify with GET /me

curl -sS -X GET "https://lock-apis-test.crebitpay.com/api/v1/partners/me" \
  -H "X-Crebit-Key-Id: YOUR_KEY_ID" \
  -H "X-Crebit-Key-Secret: YOUR_KEY_SECRET" \
  -H "X-Crebit-Environment: sandbox"

Sequence diagram

End customer

Your platform

Crebit Lock API

1. Verify credentials
GET /api/v1/partners/me
200 OK
partner_id, environment
2. Quote & lock
Customer requests a rate lock
On your UI
POST /api/v1/fx/quotes
provider_rate, market_rate, lock window, strike_mode
201 Created
quote id, locked_rate, strike_advantage_bps, expires_at
Show the locked_rate
Customer accepts on your UI
POST /api/v1/fx/contracts
quote_id
201 Created
contract id, funding_wallet_address
3. Fund the lock
Send deposit / premium on-chain
to funding_wallet_address in settlement_currency
Webhook → funds_received
Contract status moves to active
4. Customer transacts
Customer does the FX trade
On your platform at the live spot rate, any moment in the window
POST /api/v1/fx/webhooks/inbound
contract_exercised, live_execution_rate, payout_wallet_address
5. Payout
On-chain payout of FX delta
settlement_currency sent to payout_wallet_address
Webhook → payout_settled
transaction_hash, block_number

Where to go next

Ready to write code? Jump straight to the Quickstart , copy-paste flow on sandbox in 5 steps.

Concepts , lock window, currencies (fee vs. payout), forward vs. option, idempotency, errors.
API endpoints , every field with allowed-value dropdowns and sample payloads.
OpenAPI spec , for Postman / Insomnia / codegen.