Skip to main content

​
Overview

Claiming is how makers (limit order placers) settle their filled orders and receive their proceeds. Unlike takers who receive tokens immediately when executing market orders, makers must explicitly call claim() to:
  • Receive the tokens they bought
  • Unlock their remaining collateral
  • Trigger fee distribution (to protocol and referrer)

​
Maker vs Taker settlement

The system handles settlement differently for makers and takers:
AspectMaker (Limit Order)Taker (Market Order)
Settlement timingDeferred—on claimImmediate—on take
Receives proceedsWhen calling claim()Immediately during take()
Fee distributionOn claimImmediately during take
Must call claimYes ✅No ❌

​
When to claim

You should claim after your maker orders have been filled (fully or partially):
  1. After a taker fills your order: When someone executes a market order that matches your limit order
  2. Partial fills: You can claim partially filled orders to receive proceeds from the filled portion
  3. Before canceling: Claim any filled portions before canceling the remainder

​
The claiming flow

​
Step 1: Place limit order (make)

Controller.make(MakeOrderParams({
    id: bookId,
    tick: tick,
    quoteAmount: 1000e6,  // Lock 1000 USDC
    referrer: yourReferrer
}));
What happens:
  • Your quote currency (e.g., USDC) is locked in the vault
  • Order is added to the book at your specified price
  • Referrer (if specified) is stored with the order for fee sharing
  • You receive an OrderId for tracking

​
Step 2: Order gets filled (take)

When a taker matches your order:
  • Taker receives their tokens immediately
  • Protocol fee recipient and taker’s referrer (if any) receive fees immediately
  • Your order becomes claimable
  • You have not received anything yet

​
Step 3: Claim your proceeds

Controller.claim(ClaimOrderParams({
    id: orderId
}));
What happens:
  1. Calculate your claimable amount and fees
  2. Unlock your collateral (minus maker fee)
  3. Receive the base currency you bought in your vault
  4. Distribute maker fees to protocol fee recipient and your referrer (if specified)

​
Example: complete trade lifecycle

​
Setup

Book: TKN/USDC (makers BUY TKN, takers SELL TKN)
- Maker fee: 0.1% (10 bp), referrer share: 40%
- Taker fee: 0.2% (20 bp), referrer share: 50%

Alice (Maker—wants to BUY TKN):
- Places buy order: 1000 TKN at 2.0 USDC each
- Locks: 2000 USDC
- Referrer: ReferrerA

Bob (Taker—wants to SELL TKN):
- Sells 1000 TKN at market price
- Referrer: ReferrerB

​
Phase 1: Alice makes order

// Alice locks 2000 USDC to buy 1000 TKN at 2.0 USDC each
make(...)

State:
- Alice vault: 2000 USDC locked
- Book: Buy order for 1000 TKN at 2.0 USDC

​
Phase 2: Bob takes order (immediate settlement)

// Bob sells 1000 TKN
take(...)

Immediate distribution:
- Bob receives: 2000 USDC - 4 USDC (0.2% fee) = 1996 USDC ✅
- Bob's referrer (ReferrerB): 2 USDC (50% of taker fee) ✅
- Protocol fee recipient: 2 USDC (50% of taker fee) ✅

State:
- Alice's order: ✨ CLAIMABLE (but not claimed yet)
- Alice has received: NOTHING yet ❌

​
Phase 3: Alice claims (deferred settlement)

// Alice claims her filled order
claim(orderId)

Calculation:
- Alice is buying: 1000 TKN
- Alice locked: 2000 USDC
- Maker fee (in USDC): 2000 × 0.1% = 2 USDC
- To Alice's referrer (ReferrerA): 2 × 40% = 0.8 USDC
- To protocol fee recipient: 2 × 60% = 1.2 USDC

Final state:
- Alice: 1000 TKN + 1998 USDC unlocked (net cost: 2 USDC fee)
- Alice's referrer (ReferrerA): 0.8 USDC
- Protocol fee recipient: 1.2 USDC (from maker side)
- Bob: 1996 USDC
- Bob's referrer (ReferrerB): 2 USDC
- Protocol fee recipient: 2 USDC (from taker side)

​
Claim checklist

Before claiming:
  • ✅ Your order has been filled (partially or fully)
  • ✅ You have the OrderId from when you placed the order
To claim: 
Controller.claim(
    ClaimOrderParams({
        id: orderId
    })
);
After claiming:
  • ✅ Check your vault balance for the base currency you bought
  • ✅ Your locked collateral is now unlocked (minus fees)
  • ✅ Fee distribution completed (to protocol and your referrer if specified)

​
Monitoring claimable orders

To check if you have claimable orders, query the subgraph or contract: 
// Query your orders for a specific book
const orders = await bookManager.getOrders(bookId, yourAddress);

// Check claimable amount for each order
for (const order of orders) {
  const claimable = await bookManager.calculateClaimableAmount(
    order.id,
    order.tick,
    order.index
  );

  if (claimable > 0) {
    console.log(`Order ${order.id} has ${claimable} claimable`);
  }
}

​
Gas optimization

Claiming costs gas, so consider:
  • Batch claims: Claim multiple orders in one transaction
  • Timing: Wait for multiple fills before claiming
  • Trade-off: Balance gas costs vs. having access to your tokens
// Batch claim multiple orders
Controller.claim([
    ClaimOrderParams({ id: orderId1 }),
    ClaimOrderParams({ id: orderId2 }),
    ClaimOrderParams({ id: orderId3 })
]);

​
Security considerations

  • Only you can claim: Orders are tied to your address; others cannot claim your proceeds
  • No time limit: Claimable orders never expire—claim whenever convenient
  • Locked until claimed: Your locked collateral remains locked until you claim or cancel
  • Fee calculation: Maker fees are taken from your locked collateral, not from proceeds

​
See also