Request a quote

Step 1: see what is on sale

curl "$BFX/api/v2/options?pair=USD/NGN&direction=up"

{
  "pair": "USD/NGN",
  "tenors": [
    { "tenorDays": 7,  "open": true, "capped": true, "maxPayoutAvailable": "1079.4633936" },
    { "tenorDays": 30, "open": true, "capped": true, "maxPayoutAvailable": "1079.4633936" }
  ]
}

direction is up for an Up cover (pays if the rate rises) and down for a Down cover (pays if it falls).

Step 2: get today's rate

curl "$BFX/api/v2/spot?pair=USD/NGN"

{ "pair": "USD/NGN", "spot": "1332.819531" }

Use it to choose a strike, for example 2% above: 1359.475922.

Step 3: request the quote

curl -X POST $BFX/api/v2/quotes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "USD/NGN",
    "direction": "up",
    "notional": "10000",
    "tenorDays": 30,
    "structure": "capped",
    "strike": "1359.475922",
    "cap": "1495.423514"
  }'

Field	Type	Notes
`pair`	string	For example `USD/NGN`
`direction`	`up` or `down`
`notional`	decimal string, USDC	At least `10`
`tenorDays`	integer	An active tenor
`structure`	`capped` (shown to users as Limited) or `open`
`strike`	decimal string	Payables: ≥ spot and < 2× spot. Receivables: ≤ spot and > 0.5× spot.
`strikeDistanceBps`	number	Optional: the strike as a distance from today's rate, in basis points with up to 2 decimals (`200` is 2%, `2` is 0.02%). Measured from the rate the quote is priced at, so it follows the rate until you buy.
`cap`	decimal string	The limit. Required for `capped`; ignored for `open`
`capDistanceBps`	integer	Optional: the limit as a distance beyond the strike, in basis points
`pool`	resource id	Optional: quote from this pool only

A strike sent only as strike stays fixed. If today's rate moves past it before pricing, the quote is refused with INVALID_STRIKE; send strikeDistanceBps to avoid that.

The response

{
  "economic": {
    "pair": "USD/NGN", "notional": "10000", "tenorDays": 30,
    "structure": "capped", "direction": "up",
    "spot": "1332.819531", "strike": "1359.475922", "cap": "1495.423514",
    "fairRateE6": 23851, "markupBps": 11500, "offerRateE6": 27428,
    "premium": "274.28", "hedgerFee": "13.714", "totalCost": "287.994",
    "maxPayout": "1020.0000000",
    "pool": { "chain": "stellar-testnet", "contract": "CBW3...", "id": "pool/1" },
    "executionChain": "stellar-testnet"
  },
  "buyer": "C...",
  "expiresAt": 1792540000,
  "executable": { "...": "signed parameters for the contract" }
}

The values above are illustrative. expiresAt is 120 seconds after signing. Pass the whole object, unchanged, to Create protection.

How the pool is chosen

The service lists pools that sell the pair, direction, tenor and structure, and allow the strike distance. It tries them from the lowest markup up (how markups set the price), and returns the first whose free capacity covers the reserve.

Errors

Code	Meaning
`INVALID_CAP`	`capped` without a limit, or a limit outside the pool's range
`STRIKE_TOO_CLOSE`	Strike nearer spot than every pool allows; the message gives the minimum
`TENOR_DISABLED`	No pool offers this combination
`INSUFFICIENT_LIQUIDITY`	Reserve larger than every candidate's capacity
`ORACLE_NOT_READY`	No live rate for the pair
`QUOTE_EXPIRED`	Spot moved while pricing open cover; request again

Step 1: see what is on sale​

Step 2: get today's rate​

Step 3: request the quote​

The response​

How the pool is chosen​

Errors​