> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b1nary.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Public endpoints for prices, positions, accounts, bridge jobs, and trade execution.

Use the API URL for your target environment: `https://api.b1nary.app` (production) or `https://optionsprotocolbackend-staging.up.railway.app` (testnet).

## Public endpoints

No authentication required.

### GET /prices

Live option price sheet. Returns the best bid per oToken across all market makers for Base and Solana markets.

**Parameters:**

* `asset` (optional): `eth`, `btc`, `sol`, or `tslax`

**Response fields per entry:**

* `chain`, `asset`, `strike`, `expiry`, `premium`, `delta`, `iv`, `spot`
* `available_amount`, `otoken_address`
* `option_type`: `PUT` or `CALL`
* quote data: `signature`, `mm_address`, `bid_price_raw`, `deadline`, `quote_id`, `max_amount_raw`, `maker_nonce`

Returns **503** if the circuit breaker is active. Wait and retry.

```bash theme={null}
curl https://api.b1nary.app/prices?asset=eth
```

### GET /positions/\{address}

All positions for a wallet.

**Response fields:**

* `otoken_address`, `vault_id`, `amount`
* `strike_price`, `expiry`, `is_put`
* `is_settled`, `is_itm`, `settlement_type`, `outcome`
* `net_premium`, `collateral`, `asset`

```bash theme={null}
curl https://api.b1nary.app/positions/0xYourAddress
```

### GET /b1nary-account

Returns the b1nary account, members, and verified wallets linked to a Privy user.

```bash theme={null}
curl "https://api.b1nary.app/b1nary-account?privy_user_id=did:privy:..."
```

### GET /b1nary-account/by-wallet

Resolves a b1nary account from a verified wallet address.

```bash theme={null}
curl "https://api.b1nary.app/b1nary-account/by-wallet?chain=base&address=0xYourWallet"
curl "https://api.b1nary.app/b1nary-account/by-wallet?chain=solana&address=YourSolanaWallet"
```

### GET /b1nary-account/positions

Returns unified positions for all verified trading wallets in a b1nary account.

```bash theme={null}
curl "https://api.b1nary.app/b1nary-account/positions?privy_user_id=did:privy:..."
```

### GET /spot

Current spot price for an asset.

```bash theme={null}
curl https://api.b1nary.app/spot?asset=eth
```

### GET /capacity

Market capacity, max position size, market status (active/degraded/full).

```bash theme={null}
curl https://api.b1nary.app/capacity?asset=eth
```

### GET /prices/simulate

Back-test a 7-day put at a given strike. Returns premium, assignment outcome, comparison vs hold/stake/DCA.

```bash theme={null}
curl "https://api.b1nary.app/prices/simulate?strike=2400&side=sell"
```

### POST /faucet

Testnet only. Sends test tokens + gas.

```bash theme={null}
curl -X POST https://optionsprotocolbackend-staging.up.railway.app/faucet \
  -H "Content-Type: application/json" \
  -d '{"address": "0xYourAddress"}'
```

One claim per wallet. Receives 0.005 ETH (gas), 50 LETH (test WETH), 100,000 LUSD (test USDC).

## Bridge and trade endpoints

These endpoints support USDC consolidation across Base and Solana with Circle CCTP V2. Use them when a user has enough USDC across chains but not enough on the target chain for the selected quote.

### POST /api/bridge-and-trade/reserve

Reserve a Base -> Solana bridge-and-trade job before burning USDC on Base. This prevents duplicate burns for the same quote.

For Solana destinations, `mint_recipient` must be the user's Solana USDC associated token account (ATA), not the wallet owner. If the ATA does not exist, backend validates and creates it with the operator hot wallet as payer.

```bash theme={null}
curl -X POST https://api.b1nary.app/api/bridge-and-trade/reserve \
  -H "Content-Type: application/json" \
  -d '{
    "source_chain": "base",
    "dest_chain": "solana",
    "user_id": "did:privy:...",
    "mint_recipient": "SolanaUsdcAta",
    "burn_amount": "12000000",
    "quote_id": "100123",
    "signed_trade_tx": null
  }'
```

### POST /api/bridge-and-trade

Create or finalize a bridge job after the source burn transaction exists. Used for Base -> Solana bridge-and-trade and bridge-only flows.

```bash theme={null}
curl -X POST https://api.b1nary.app/api/bridge-and-trade \
  -H "Content-Type: application/json" \
  -d '{
    "burn_tx_hash": "0x...",
    "source_chain": "base",
    "dest_chain": "solana",
    "user_id": "did:privy:...",
    "mint_recipient": "SolanaUsdcAta",
    "burn_amount": "12000000",
    "quote_id": "100123",
    "signed_trade_tx": null
  }'
```

### POST /api/bridge/solana-cctp-burn/prepare

Prepare a sponsored Solana -> Base CCTP burn transaction. Backend uses the operator as fee payer; the user signs only as the Solana USDC owner.

```bash theme={null}
curl -X POST https://api.b1nary.app/api/bridge/solana-cctp-burn/prepare \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "SolanaTradingWallet",
    "dest_chain": "base",
    "mint_recipient": "0xBaseSmartTradingAccount",
    "burn_amount": "12000000",
    "max_fee": "0",
    "min_finality_threshold": 2000
  }'
```

### POST /api/bridge/solana-cctp-burn/submit

Submit the user-signed Solana burn transaction. Backend broadcasts it, creates the bridge job, waits for attestation, and mints on Base.

```bash theme={null}
curl -X POST https://api.b1nary.app/api/bridge/solana-cctp-burn/submit \
  -H "Content-Type: application/json" \
  -d '{
    "signed_transaction_base64": "...",
    "dest_chain": "base",
    "user_id": "did:privy:...",
    "mint_recipient": "0xBaseSmartTradingAccount",
    "burn_amount": "12000000",
    "quote_id": "100123",
    "signed_trade_tx": null
  }'
```

### GET /api/bridge-status/\{job\_id}

Poll bridge progress. Terminal statuses are `completed`, `mint_completed`, `mint_completed_trade_failed`, or `failed`.

```bash theme={null}
curl https://api.b1nary.app/api/bridge-status/job-id
```

## Market maker endpoints

Require `X-API-Key` header. See the [Market Making guide](/market-making/overview) for details.

| Method | Endpoint        | Description                                        |
| ------ | --------------- | -------------------------------------------------- |
| POST   | `/mm/quotes`    | Submit signed EIP-712 quotes                       |
| GET    | `/mm/quotes`    | Active, non-expired quotes                         |
| DELETE | `/mm/quotes`    | Cancel all active quotes                           |
| GET    | `/mm/fills`     | Filled trades                                      |
| GET    | `/mm/positions` | Open positions by oToken                           |
| GET    | `/mm/exposure`  | Risk summary                                       |
| GET    | `/mm/market`    | Market data: spot, IV, fee, gas, available oTokens |
| WS     | `/mm/stream`    | Real-time fill notifications                       |