Quickstart

Quickstart (sandbox)

End-to-end copy-paste flow on https://lock-apis-test.crebitpay.com. Replace ids after each step. Full per-field schemas live on API endpoints , this page is the fastest path to a working integration.

0. Get API keys

Crebit provisions sandbox and production API keys during a short onboarding call. Book a slot and we'll get you live on sandbox the same day:

Book onboarding call →

Once you have keys, verify them any time with GET /api/v1/partners/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"

1. Quote

Price a rate lock for your customer. Set the corridor, notional, lock window, settlement chain, fee currency, and payout currency.

Request body

json

{
  "customer_reference_id": "partner-cust-ref-2026-0042",
  "customer_name": "Acme Imports Pvt Ltd",
  "contract_type": "forward",
  "direction": "USD_TO_BRL",
  "notional_currency": "USD",
  "notional_amount": "50000.00",
  "provider_rate": "5.42",
  "market_rate": "5.4180",
  "market_rate_timestamp": "2026-05-24T16:00:00Z",
  "provider_extra_spread": "0.0005",
  "strike_mode": "cip_fair",
  "window_start": "2026-08-04T00:00:00Z",
  "window_end": "2026-08-11T00:00:00Z",
  "chain": "ethereum",
  "settlement_currency": "USDC"
}

How to call

curl -sS -X POST "https://lock-apis-test.crebitpay.com/api/v1/fx/quotes" \
  -H "Content-Type: application/json" \
  -H "X-Crebit-Key-Id: YOUR_KEY_ID" \
  -H "X-Crebit-Key-Secret: YOUR_KEY_SECRET" \
  -H "X-Crebit-Environment: sandbox" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_reference_id":"partner-cust-ref-2026-0042","customer_name":"Acme Imports Pvt Ltd","contract_type":"forward","direction":"USD_TO_BRL","notional_currency":"USD","notional_amount":"50000.00","provider_rate":"5.42","market_rate":"5.4180","market_rate_timestamp":"2026-05-24T16:00:00Z","provider_extra_spread":"0.0005","strike_mode":"cip_fair","window_start":"2026-08-04T00:00:00Z","window_end":"2026-08-11T00:00:00Z","chain":"ethereum","settlement_currency":"USDC"}'

Response (201 Created)

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "created",
  "locked_rate": "5.42",
  "strike_mode": "cip_fair",
  "target_strike": null,
  "strike_advantage_bps": 12,
  "provider_extra_spread": "0.0005",
  "premium_amount": "1565.00",
  "deposit_amount": "5000.00",
  "total_amount": "6565.00",
  "window_start": "2026-08-04T00:00:00Z",
  "window_end": "2026-08-11T00:00:00Z",
  "chain": "ethereum",
  "settlement_currency": "USDC",
  "expires_at": "2026-05-24T16:16:30Z",
  "created_at": "2026-05-24T16:15:00Z"
}

2. Lock (create the contract)

Customer accepts the quote → convert it into a binding contract by POSTing the quote_id.

Request body

json

{
  "quote_id": "22222222-2222-4222-8222-222222222222",
  "partner_transaction_reference": "platform-tx-9901"
}

How to call

curl -sS -X POST "https://lock-apis-test.crebitpay.com/api/v1/fx/contracts" \
  -H "Content-Type: application/json" \
  -H "X-Crebit-Key-Id: YOUR_KEY_ID" \
  -H "X-Crebit-Key-Secret: YOUR_KEY_SECRET" \
  -H "X-Crebit-Environment: sandbox" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"quote_id":"22222222-2222-4222-8222-222222222222","partner_transaction_reference":"platform-tx-9901"}'

Response (201 Created)

json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "crebit_contract_reference": "crebit_lock_7f3a9c2b1d",
  "locked_rate": "5.42",
  "provider_rate_at_lock": "5.42",
  "market_rate_at_lock": "5.4180",
  "premium_amount": "1565.00",
  "deposit_amount": "5000.00",
  "total_amount": "6565.00",
  "window_start": "2026-08-04T00:00:00Z",
  "window_end": "2026-08-11T00:00:00Z",
  "chain": "ethereum",
  "settlement_currency": "USDC",
  "funding_wallet_address": "0xCrebitFundingWalletForThisContract",
  "created_at": "2026-05-24T16:20:00Z",
  "max_transaction_amount": "50000.00"
}

3. Notify funds in route

Once you've dispatched the upfront fee (deposit for forward, premium for option) on-chain, post the inbound webhook so Crebit advances the contract to active.

json

{
  "event_type": "funds_in_route",
  "fx_contract_id": "33333333-3333-4333-8333-333333333333",
  "payment_type": "deposit",
  "amount": "5000.00",
  "currency": "USDC",
  "chain": "ethereum",
  "transaction_hash": "0xabc123…",
  "source_wallet_address": "0xPartnerTreasury…"
}

curl -sS -X POST "https://lock-apis-test.crebitpay.com/api/v1/fx/webhooks/inbound" \
  -H "Content-Type: application/json" \
  -H "X-Crebit-Key-Id: YOUR_KEY_ID" \
  -H "X-Crebit-Key-Secret: YOUR_KEY_SECRET" \
  -H "X-Crebit-Environment: sandbox" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"event_type":"funds_in_route","fx_contract_id":"33333333-3333-4333-8333-333333333333","payment_type":"deposit","amount":"5000.00","currency":"USDC","chain":"ethereum","transaction_hash":"0xabc123…","source_wallet_address":"0xPartnerTreasury…"}'

4. Trigger payout (customer transacts)

The moment the customer transacts within the lock window, post contract_exercisedwith the live rate and the customer's payout wallet. This is the call that triggers Crebit to pay out the FX delta on-chain.

json

{
  "event_type": "contract_exercised",
  "fx_contract_id": "33333333-3333-4333-8333-333333333333",
  "executed_at": "2026-08-07T13:42:00Z",
  "live_execution_rate": "5.51",
  "payout_wallet_address": "0xEndUserWallet…",
  "payout_currency": "USDC",
  "chain": "ethereum"
}

curl -sS -X POST "https://lock-apis-test.crebitpay.com/api/v1/fx/webhooks/inbound" \
  -H "Content-Type: application/json" \
  -H "X-Crebit-Key-Id: YOUR_KEY_ID" \
  -H "X-Crebit-Key-Secret: YOUR_KEY_SECRET" \
  -H "X-Crebit-Environment: sandbox" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"event_type":"contract_exercised","fx_contract_id":"33333333-3333-4333-8333-333333333333","executed_at":"2026-08-07T13:42:00Z","live_execution_rate":"5.51","payout_wallet_address":"0xEndUserWallet…","payout_currency":"USDC","chain":"ethereum"}'

5. Receive payout_settled webhook

Crebit sends the on-chain payout to payout_wallet_address, then POSTs payout_settled to your configured webhook_url with the on-chain transaction_hash. That's the authoritative "paid" signal, update your records and you're done.

Full outbound webhook schema, signature verification, and retry rules are on API endpoints → Outbound webhooks.