Protection endpoints
Pricing: how a quote's premium, fees and payout are worked out is in Premium calculation and Payout calculation.
POST /quotes (auth)
Request:
| Field | Type | Required |
|---|---|---|
pair | string | Yes |
direction | up or down | Yes |
notional | decimal string | Yes |
tenorDays | integer | Yes |
structure | capped (Limited) or open | Yes |
strike | decimal string | Yes |
cap | decimal string, the limit | For capped |
strikeDistanceBps | number, basis points with up to 2 decimals (2 is 0.02%, 0.15 is 0.0015%) | No |
capDistanceBps | integer, basis points beyond the strike | No |
pool | resource id string | No |
With strikeDistanceBps, the strike is measured from the exact rate the quote is priced at, rounded away from it, so it never falls short of a pool's closest strike when the rate moves. Without it, strike is used as given; if today's rate has moved past it, the quote is refused with INVALID_STRIKE. Each pool's minStrikeDistanceBps still applies (STRIKE_TOO_CLOSE).
Response, ProtectionQuote:
| Field | Meaning |
|---|---|
economic.spot | Rate the quote was priced at; becomes the position's rate at purchase |
economic.strike, economic.cap | Terms (cap is the limit, computed for open) |
economic.fairRateE6 | Engine fair rate |
economic.markupBps | The chosen pool's markup for the tenor |
economic.offerRateE6 | fairRateE6 × markupBps / 10000, rounded down |
economic.premium, hedgerFee, totalCost | USDC |
economic.maxPayout | Reserve |
economic.pool | Pool resource id |
economic.executionChain | stellar-testnet |
buyer | The user's Stellar wallet the quote is bound to |
expiresAt | Unix seconds; 120 s after signing |
executable | Signed contract parameters; pass back unchanged |
POST /hedges/prepare (auth)
Body: { "quote": <ProtectionQuote> }. Returns { transactions: PreparedTransaction[] } calling buy_protection with max_cost = totalCost and deadline = quote time + 120.
GET /hedges (auth)
All the user's positions with settlement: { hedges: [{ position, pair, settlement }] }.
GET /hedges/:ref
One position: { position, settlement }.
position fields: ref, positionId, poolId, hedger, structure, direction, status (active, settled, claimed), tenorDays, createdAt, expiry, notional, spot, strike, cap, fairRateE6, premiumRateE6, premium, fee, maxPayout, settlementPrice, payout.
settlement fields: settlementPrice, grossPayout, fee, netPayout, status (pending, settled_no_payout, settled_claimable, claimed).
POST /hedges/:ref/claim/prepare (auth)
Returns the claim_payout transaction.