For Hedgers

You're integrating BlockFinaX because you want to buy FX protection — either for yourself or on behalf of your users (an exporter, a treasury, a remittance corridor, a payroll provider, an automated vault).

This page walks you end-to-end.

What you're buying

For a chosen pair (e.g. USD/GHS), you're buying a payout that fires automatically if the rate lands inside a pre-defined zone at expiry.

You pick:

• Which event to buy into (each event is a pair × strike × cap × expiry combination)
• Notional — the size of your exposure, denominated in the payment token (USDC)
• maxCost — slippage cap; if premium + fees exceed this, the tx reverts
• deadline — Unix-seconds after which the tx is no longer valid

You get back a position identified by positionId that you (or your user) later call claimPayout(positionId) against, if the event triggers.

End-to-end: buy protection

Step 1 — Discover the event

curl https://api.blockfinax.com/v1/hedge/events/8453/12

Read the core fields: strike, payoutCap (via the /range endpoint), expiryDate, premiumRate, and strikeAbove to confirm the direction matches your exposure.

Also check capacity:

curl https://api.blockfinax.com/v1/hedge/events/8453/12/utilization

{
  "data": {
    "totalLiquidity": "100000000",
    "totalExposure":  "850000000",
    "availableCapacity": "7050000",
    "utilizationRate":   "29942780"
  }
}

availableCapacity (in USDC base units) is how much additional notional the pool can write before it hits its bound. If your notional exceeds it, the tx will revert.

Step 2 — Approve USDC

Before any tx that pulls USDC, the user's wallet must have approved the Diamond as a spender:

curl -X POST https://api.blockfinax.com/v1/tx/erc20/approve \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "spender": "0xbCC51E62C4948FD35ab505bd71804C849601e4Ef",
    "amount": "110000000"
  }'

The response is a BuiltTx. Sign with the user's wallet and broadcast.

amount should be at least premium + platformFee + buffer. A 10% buffer above the quoted premium is typical.

Step 3 — Build buyProtection

curl -X POST https://api.blockfinax.com/v1/tx/hedge/buy-protection \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "eventId": 12,
    "notional": "100000000",
    "maxCost":  "110000000",
    "deadline": "1782182400"
  }'

Sign + send. After the tx confirms, parse the receipt for the PositionCreated event to recover positionId.

Step 4 — Wait for expiry

Poll or subscribe to:

curl https://api.blockfinax.com/v1/hedge/events/8453/12/stats

When settledAt > 0, settlement has fired. triggered tells you whether the rate landed in the range. If triggered: false, the option expired worthless — there's nothing to claim.

Step 5 — Claim if triggered

curl -X POST https://api.blockfinax.com/v1/tx/hedge/claim-payout \
  -H "Content-Type: application/json" \
  -d '{ "chainId": 8453, "positionId": 7 }'

Sign + send. The USDC lands in the wallet that submitted the tx (the same hedger recorded on the position).

You can read the position's state any time:

curl https://api.blockfinax.com/v1/hedge/positions/8453/7

{
  "data": {
    "id": 7,
    "eventId": 12,
    "hedger": "0xdead...",
    "notional": "100000000",
    "premiumPaid": "2300000",
    "platformFeePaid": "500000",
    "payoutAmount": "5420000",
    "status": 2,
    "claimed": false
  }
}

payoutAmount > 0 and claimed: false means you have something to claim.

Showing all of a user's positions

curl https://api.blockfinax.com/v1/hedge/positions/8453/wallet/0xUSERADDR

Returns every position ID the user owns. Then GET /positions/:chainId/:id for each to render the full state.

A pricing pre-check

Before you build buyProtection, you can hit the pricing engine to confirm the on-chain premiumRate is reasonable:

curl -X POST https://api.blockfinax.com/v1/pricing/quote \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "USD/GHS",
    "strike": 11.4, "payoutCap": 12.0,
    "expiryUnixSeconds": 1782182400,
    "notional": 100, "strikeAbove": true
  }'

If the engine's premiumRate is far from the event's on-chain premiumRate, the underwriter might have set an off-market price. That's not necessarily wrong — they might be quoting a different vol regime — but it's worth flagging in your UI.

Failure modes (and what to render)

What happened	Why	What to show
Tx reverts with "Insufficient allowance"	User didn't approve enough USDC	Re-run the approve step with a larger amount
Tx reverts with "Past deadline"	Tx mined after deadline	Increase the deadline and rebuild
Tx reverts with "Exceeds capacity"	Pool full	Tell the user; suggest a smaller notional or a different event
Tx reverts with "Cost exceeds maxCost"	Premium moved between quote and submission	Re-fetch event premium rate, raise maxCost
claimPayout reverts with "Already claimed"	The position has already been claimed	The user already redeemed; show claimed: true

Wiring it into a payment / treasury app

The typical pattern:

Hedge sizing is usually a percentage of the user's notional — e.g. 80% — to keep the premium reasonable while still capping the worst-case loss. The right number is your product decision, not the protocol's.

What you don't have to think about

• Custody. The user keeps custody of their wallet at all times. You're just constructing the calldata.
• Settlement. Once the event expires, the oracle network does the work. You only have to call claimPayout for users with positive payouts.
• Counter-party. The pool is funded by LPs whose capital is locked until expiry, enforced by the contract. There's no broker to fail.