Skip to main content

For Liquidity Providers

You're integrating BlockFinaX because you want to earn the premium flow — deposit USDC into the pool of an event, get a pro-rata share of every premium hedgers pay, and withdraw your capital + premiums at expiry. Worst case (triggered event): your capital is reduced by the share of payouts.

This page walks you end-to-end.

What you're earning, what you're risking​

You earn: the premium income from every hedger in the event, split pro-rata by the LP shares you hold.

You risk: if the event triggers (settlement lands in the payout range), the contract pays hedgers from the pool. Your share of capital is reduced by your pro-rata share of that payout.

Bounded downside: the contract enforces that totalMaxPayout never exceeds totalLiquidity. You can lose up to your full deposit on a single event, but never more.

Picking an event​

This is the most important step. Read three things:

  1. The pricing reasonableness. Compare the on-chain premiumRate against what the pricing engine would quote for the same parameters. Big divergence = underwriter is quoting their own view of vol; decide if you agree.
  2. The classification. Is this a developed, mainstreamEM, or frontierEM pair? Frontier corridors pay higher premiums but have higher tail risk.
  3. The current utilization. A heavily-utilized pool is concentrated risk; a barely-utilized one means your premiums-per-day are low until it fills.
curl https://api.blockfinax.com/v1/hedge/events/8453/12
curl https://api.blockfinax.com/v1/hedge/events/8453/12/utilization
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 }'

End-to-end: deposit, earn, withdraw​

Step 1 — Approve USDC​

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

Step 2 — Deposit​

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

Sign + send. After confirmation, parse the receipt for the DepositCreated event to recover depositId. Or read the LP's deposit IDs by wallet:

curl https://api.blockfinax.com/v1/hedge/deposits/8453/wallet/0xLPADDR

Step 3 — Watch the deposit accrue​

curl https://api.blockfinax.com/v1/hedge/deposits/8453/3
{
  "data": {
    "id": 3,
    "eventId": 12,
    "lp": "0xLPADDR",
    "amount":          "10000000000",
    "shares":          "10000000000",
    "premiumsEarned":  "1200000",
    "premiumsClaimed": "0",
    "withdrawn": false
  }
}

premiumsEarned − premiumsClaimed is what you can call claimPremiums for right now, without touching your capital.

Step 4 — Claim premiums (optional, can be done any time)​

You don't have to wait until expiry. Premiums are accrued continuously as hedgers buy in.

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

Step 5 — Withdraw capital (after expiry)​

Once the event has settled, withdrawCapital releases your principal share back to your wallet:

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

The amount you receive is your pro-rata share of the pool's remaining capital after all hedger payouts have been allocated. If the event didn't trigger, you get back your full principal. If it did, you get back your principal minus your share of the payouts.

Important: pool-open setting​

The creator can flip poolOpen at any time via setPoolSettings. When poolOpen = false, deposit reverts. Always check the current state before trying:

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

poolOpen: false in the response means the underwriter has stopped accepting new LP capital for this event. (Typical reason: pool is approaching fully-allocated and the creator doesn't want more capital diluting earned premiums.)

What "pool capacity" means for an LP​

totalExposure / totalLiquidity is the pool's leverage. The contract enforces that totalMaxPayout ≤ totalLiquidity, which means your capital is bounded. But within that bound, a higher-leveraged pool means a higher per-dollar premium rate — you're earning more premium per unit of risk.

Use the utilization endpoint to see this live:

curl https://api.blockfinax.com/v1/hedge/events/8453/12/utilization
{
  "data": {
    "totalLiquidity":     "100000000",   // 100 USDC of capital
    "totalExposure":      "850000000",   // 850 USDC of hedger notional
    "availableCapacity":  "7050000",     // capacity left
    "utilizationRate":    "29942780"     // ~30% utilization (1e8 scale)
  }
}

Yield modeling​

A rough formula for annualized yield at the moment you deposit:

yield ≈ (premiumRate × (totalExposure / totalLiquidity)) × (365 / daysToExpiry)

Then subtract:

  • Your expected share of payouts (depends on settlement probability — the pricing engine's breakdown.coveragePercent is a useful sanity check)
  • LP profit fee (a small percentage of premium income, set in getHedgeFeeConfig as lpProfitFeeRate)

If you're building an LP-facing product, surface this as "expected APY" in your UI, computed live from the current totalExposure / totalLiquidity ratio and the pricing engine's settlement probability for the event.

Multi-event diversification​

A single event is a single FX corridor's risk. To smooth returns, deposit into multiple events on different pairs and at different expiries. The protocol supports this naturally — every event has its own pool, and getLpDepositIds lists every deposit a wallet owns:

curl https://api.blockfinax.com/v1/hedge/deposits/8453/wallet/0xLPADDR

A yield-aggregator vault that auto-allocates across events would read the pricing engine for each candidate event and pick the ones with the best risk-adjusted return.