Flying Tulip Leverage Orderbook API - Filler Guide

orderbook-filler-guide.md

Leverage Orderbook API - Filler Guide

Endpoints

Method	Path	Description
GET	/leverage/orders/stream	SSE stream — real-time order events
GET	/leverage/orders?status=pending	Poll pending orders
POST	/leverage/orders/{id}/claim	Claim an order (30s TTL)
DELETE	/leverage/orders/{id}/claim	Release a claim
POST	/leverage/orders/{id}/fill	Report fill with tx hash
GET	/leverage/config	Get config (engine, session manager, executor, mode)

1. Stream Orders (SSE)

curl -N http://localhost:8082/leverage/orders/stream

Events:

• order:new — new pending order
• order:claimed — order claimed by a filler
• order:filled — order filled on-chain
• order:cancelled — order cancelled
• order:released — claim expired, order back to pending
• order:expired — order expired (validTo passed)

Example event:

data: {
  "type": "order:new",
  "order": {
    "id": "lev_7d6ff702...",
    "user": "0x6A7Daf...",
    "order": {
      "sellToken": "0x039e2fB6...",
      "buyToken": "0xE5DA20F1...",
      "sellAmount": 50000000000000000000,
      "buyAmount": 47000000000000000000,
      "validTo": 1775398654
    },
    "session": {
      "sessionId": "0x567e9dfa...",
      "target": "0x2A6AeF0A...",
      "dataHash": "0x5171669f...",
      "nonce": 0,
      "deadline": 1775398654,
      "executor": "0x964d42D4..."
    },
    "delegateSignature": "base64...",
    "sigType": "session",
    "status": "pending",
    "orderType": "open"
  }
}

2. Poll Pending Orders

curl http://localhost:8082/leverage/orders?status=pending

3. Claim an Order

curl -X POST http://localhost:8082/leverage/orders/lev_7d6ff702.../claim \
  -H "Content-Type: application/json" \
  -d '{"fillerId": "0xYOUR_FILLER_ADDRESS"}'

Response:

{
  "success": true,
  "orderId": "lev_7d6ff702...",
  "claimExpiry": 1775395086,
  "order": { ... }
}

Claim TTL is 30 seconds. If you don't fill in time, the order returns to pending.

4. Fill the Order On-Chain

Use the order data from the claim response to call the contract:

# For session-based orders, call openLeverageFlashWithSession on the engine
# The delegateSignature from the order is passed to the contract

cast send <ENGINE> "openLeverageFlashWithSession(tuple,address,bytes,tuple,bytes)" \
  <order_tuple> <fillTarget> <fillData> <sessionCall_tuple> <delegateSignature> \
  --from <YOUR_FILLER> --private-key <PK> --rpc-url https://rpc.soniclabs.com

5. Report Fill

curl -X POST http://localhost:8082/leverage/orders/lev_7d6ff702.../fill \
  -H "Content-Type: application/json" \
  -d '{"fillerId": "0xYOUR_FILLER_ADDRESS", "txHash": "0xabc123..."}'

6. Release a Claim (optional)

If you can't fill, release the claim so another filler can try:

curl -X DELETE http://localhost:8082/leverage/orders/lev_7d6ff702.../claim \
  -H "Content-Type: application/json" \
  -d '{"fillerId": "0xYOUR_FILLER_ADDRESS"}'

Config

curl http://localhost:8082/leverage/config

{
  "chainId": 146,
  "signingChainId": 146,
  "sessionManager": "0x52Ef449D44cC4205fa44bF644dEE15611FC30734",
  "sessionManagerDomainName": "ftUSD SessionManager",
  "leverageRfqEngine": "0x2A6AeF0A4bC1933Cf178D68A388Ca3a29CD52d92",
  "executorAddress": "0x964d42D4C64E1645D5771FD1c972BBF184aC596E",
  "mode": "executor"
}

Modes:

• executor — accepts orders AND fills them (built-in filler)
• orderbook — accepts orders only, external fillers do the filling

Signature Types

Orders support three signature types (sigType field):

• session — session-based (SessionManager + delegate signature)
• eip712 — raw EIP-712 owner signature over order
• erc1271 — smart contract wallet (ERC-1271)

Verified on Sonic Mainnet

TX: https://sonicscan.org/tx/0x7943525132bf679fb6...
Action: Open Leverage (flash)
Sell: 50 wS → Buy: ~47 stS
DEX: ODOS
Engine: 0x2A6AeF0A (dev)