Claiming

​

Overview

• Receive the tokens they bought
• Unlock their remaining collateral
• Trigger fee distribution (to protocol and referrer)

​

Maker vs Taker settlement

​

When to claim

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
}));

• 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)

• 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
}));

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

• ✅ Your order has been filled (partially or fully)
• ✅ You have the OrderId from when you placed the order

Controller.claim(
    ClaimOrderParams({
        id: orderId
    })
);

• ✅ 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

// 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

• 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

• Vaults & deposits - vault mechanics and collateral
• Referrers - understanding the referrer fee system
• Controller - the main trading interface
• Claim orders guide - how to claim filled orders