For Underwriters

You're integrating BlockFinaX because you create events — you're the price-maker. You understand option pricing, you have a view on FX volatility for a corridor, and you want to put that view to work by writing on-chain hedges and earning the underwriter slice of the resulting flow.

This page is for investment banks, FX desks, NDF traders, options market makers, and finance professionals comfortable with Black–Scholes-style pricing. If you'd rather just deposit into someone else's event, you're an LP.

What you do

You earn:

1. Creator loyalty fee — a percentage of every hedger's platform-fee component. Continuous accrual; withdrawn via withdrawCreatorEarnings.
2. LP premium share — on the initial liquidity you seeded, you're an LP in your own event and earn pro-rata premiums.

You're at risk of:

• The same downside any LP has — your seeded capital can be reduced if the event triggers.
• Reputational risk — if you systematically mis-price events, hedgers will stop buying and external LPs will stop seeding alongside you.

The economic case

If you have a credible view that the market is overpaying for protection on a pair (vol is sticky high, but realized has been low), you can write events at a premium rate that's slightly below the market consensus, capture the flow, and let your seeded capital earn the LP spread.

Conversely, if you think the market is underpaying (everyone's complacent about a known event risk), you can:

• Not create new events on that pair, or
• Create events with strikes well inside the danger zone and price them appropriately

The pricing engine is advisory only — it is never enforced. The contract accepts whatever premiumRate you pass to createEvent; there is no on-chain check against the engine's number, and no auto-update over the event's lifetime.

Most professional underwriters consult the engine as a sanity check ("does my number land roughly where Garman–Kohlhagen would put it?") and then ship their own rate, sized by:

• Their own vol view (forward-looking catalysts the engine doesn't model)
• Better data than ours (tick-level / NDF curves / options-market skews)
• Their book's current exposure and risk appetite
• A pricing methodology specific to the pair class (NDF-anchored, etc.)

To override, pass signature = "0x" + quoteTimestamp = "0" + quoteNonce = ZeroHash. This is self-priced mode — the contract accepts the rate as given. See Concepts → Setting your own price for the full rationale and the four common deviation reasons.

Pricing inputs you should care about

Before you create an event, look at:

What to read	Endpoint	Why
Reference fair value	POST /v1/pricing/quote	What the engine thinks. Use as a sanity check; you'll likely deviate.
Current vol estimate	GET /v1/pricing/health	See pairs[] for which pairs have enough historical closes to price.
Existing events on the pair	GET /v1/hedge/events/:chainId/total then iterate	Avoid stepping on a similar live event.
The settlement oracle config	GET /v1/oracle/config/:chainId	Confirm requiredSigners + toleranceBps match your assumptions.

End-to-end: create an event

Step 1 — (optional) Get a signed quote

If you want the engine's signature so the contract accepts the price as attested:

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": 1000000,
    "strikeAbove": true,
    "chainId": 8453,
    "diamondAddress": "0xbCC51E62C4948FD35ab505bd71804C849601e4Ef",
    "creator": "0xYourCreatorWalletAddress"
  }'

You'll get back attestation.signature, attestation.quoteTimestamp, and attestation.quoteNonce. They expire in 120 seconds. Build and send the createEvent tx immediately.

If you'd rather price the event yourself, skip this step and pass signature = "0x" + quoteTimestamp = 0 + quoteNonce = ZeroHash in step 3.

Step 2 — Approve USDC

You're paying two things up front:

• The creationFee (set via getHedgeFeeConfig)
• The initialLiquidity you're seeding the pool with

Approve at least creationFee + initialLiquidity against the Diamond:

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

Step 3 — Build createEvent

curl -X POST https://api.blockfinax.com/v1/tx/hedge/create-event \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "name":              "USD/GHS · Q2 wide",
    "underlying":        "USD/GHS",
    "strike":            "11400000",
    "payoutCap":         "12000000",
    "premiumRate":       "23000",
    "expiry":            "1782182400",
    "allowExternalLp":   true,
    "initialLiquidity":  "100000000000",
    "initialRate":       "11070000",
    "strikeAbove":       true,
    "paymentToken":      "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "signature":         "0x",
    "quoteTimestamp":    "0",
    "quoteNonce":        "0x0000000000000000000000000000000000000000000000000000000000000000"
  }'

All numeric fields are decimal strings in fixed-point:

• strike, payoutCap, initialRate — 1e6 precision (so 11.40 = "11400000")
• premiumRate — 1e6 precision (so 2.3% = "23000")
• initialLiquidity — payment-token decimals (USDC has 6 → 100,000 USDC = "100000000000")
• expiry — Unix seconds

Sign + send. The EventCreated log gives you eventId.

Managing a live event

Once the event is live, you have three creator-only controls:

Pause new LP deposits (or re-open)

curl -X POST https://api.blockfinax.com/v1/tx/hedge/set-pool-settings \
  -H "Content-Type: application/json" \
  -d '{ "chainId": 8453, "eventId": 12, "poolOpen": false, "allowExternalLp": true }'

Pool full? Close it. Want to re-open? Flip back to true.

Withdraw your accumulated creator earnings

Continuously accrues as hedgers buy in:

curl -X POST https://api.blockfinax.com/v1/tx/hedge/withdraw-creator-earnings \
  -H "Content-Type: application/json" \
  -d '{ "chainId": 8453, "eventId": 12 }'

Withdraw your seeded LP capital after expiry

Because you seeded the initial liquidity, you also own a deposit. After settlement, claim premiums and withdraw capital like any other LP:

# get your depositId
curl https://api.blockfinax.com/v1/hedge/deposits/8453/wallet/0xYourCreatorAddr

# then claim premiums + withdraw capital
curl -X POST https://api.blockfinax.com/v1/tx/hedge/claim-premiums \
  -d '{ "chainId": 8453, "depositId": 1 }'
curl -X POST https://api.blockfinax.com/v1/tx/hedge/withdraw-capital \
  -d '{ "chainId": 8453, "depositId": 1 }'

Listing all events you've created

curl https://api.blockfinax.com/v1/hedge/creators/8453/wallet/0xYourCreatorAddr

Returns the IDs of every event you created. Iterate through /events/:id and /stats to render your book.

Common patterns

Series of weekly events

Create a fresh event every Monday with a 7-day expiry and a strike centered on the current spot. Predictable cadence; LPs and hedgers know when to show up. Roll your unutilized capital from last week into this week's event via withdrawCapital + deposit.

Wide-range events for treasury hedgers

Strike at 5% out-of-the-money, cap at 15% out. Low premium, wide payoff zone — good for users who just want "disaster protection" on their treasury balance. You'll have low utilization but consistent flow.

Tight-range events for speculators

Strike at-the-money, cap 3% away. High premium per unit, fast utilization, short expiries (1–3 days). Higher tail risk on your seeded capital, but the premium-per-day is much better if you're right about realized vol.

What you can't do

• You can't retroactively change strike, payoutCap, premiumRate, or expiry. Those are immutable from createEvent.
• You can't force-settle the event early. Settlement only happens after expiryDate once the oracle network reaches consensus.
• You can't withdraw the creator's loyalty fee until after some hedger has paid premium — there has to be something to withdraw.

A note on liability and reputation

This protocol does not vet underwriters. Anyone can create an event. Hedgers and LPs decide whether to trust the events you've created.

If you're operating a venue (a desk, a fund) that creates events at scale, sign every event with a known wallet, publish your strategy, and let your on-chain history (via getCreatorEventIds) be your reputation. The protocol makes that history immutable and public.