ORDERBOOK QUEST API

Verify Orderbook Swaps

Verify if a user has placed and matched (swapped) limit orders for your custom token on the central limit orderbook (CLOB) indexer. Ideal for creating custom token trading campaigns.

← Return to Developer Portal

How it works

The central limit orderbook tracks orders placed by users. When a buy or sell limit order matches another order on-chain, it represents a swap. The API queries the poap-subgraph:

Searches the Order entity for all records owned by the user (owner).
Filters the orders to match only those representing the project's token in the `market` base or quote.
Checks the order's status: Orders in `FILLED_UNCLAIMED`, `SETTLED`, or `PARTIALLY_FILLED` confirm that swaps successfully occurred.
Evaluates if the count of filled orders meets the campaign threshold (minSwaps).

API Endpoint Specs

This endpoint supports both GET and POST and has CORS enabled.

GET

Verify Orderbook Swaps Status

https://litvmswap.com/api/orderbook-verify-swaps?address=[wallet_address]&token=[your_token_address]&minSwaps=[count]&counterToken=[counter_token_address]

Request Parameters

Parameter	Type	Requirement	Description
`address`	String	Required	The user's EVM wallet address to verify (case-insensitive).
`token`	String	Optional	Your token's contract address. Filters user orders to this specific asset.
`minSwaps`	Number	Optional	The number of filled orders required. Defaults to `1`.
`counterToken`	String	Optional	Filters swaps specifically against a counter asset (e.g. native zkLTC).

📊 Volume Tracking Questions

Is checking volume possible against zkLTC / Native token?

Yes, with limitations. You can query swaps specifically against native zkLTC (represented by the zero address: 0x0000000000000000000000000000000000000000) by passing counterToken=0x0000000000000000000000000000000000000000.

⚠️ Historical Volume Limitation: In the orderbook subgraph, when an order's status transitions to SETTLED (fully filled and claimed), its claimableUnits are reset to 0 and the original placed size is not saved under a cumulative filled field on the Order schema.

Therefore, while you can retrieve matched swap counts and verify if trades occurred successfully, exact historical volume accumulation is not fully possible for settled orders. We recommend designing campaigns around status-based checks (swap count) instead of accumulated volume for orderbook quests.

JSON Response Structure

API JSON Response Example

{
  "success": true,
  "address": "0x23d542dcefb00b1f4268e67a0ec1ef4de0a58fe2",
  "token": "0xdf69970b2fe416339187aa41d39882e864984ce9",
  "counterToken": "0x0000000000000000000000000000000000000000",
  "verification": {
    "totalSwaps": 10,
    "minSwapsRequired": 1,
    "isEligible": true,
    "remainingSwapsNeeded": 0,
    "unclaimedVolumeUnits": "9999000",
    "note": "Note: Volume calculations for SETTLED orders are reset to 0 in this subgraph. Use status checks (FILLED_UNCLAIMED/SETTLED/PARTIALLY_FILLED) to verify swaps."
  },
  "proofs": {
    "orderCount": 10,
    "orders": [
      {
        "id": "3156615923078993896613747117076284775081499773140419317205--10987-0",
        "status": "FILLED_UNCLAIMED",
        "priceTick": -10987,
        "openUnits": "0",
        "claimableUnits": "9999000",
        "createdAtTimestamp": 1778763294,
        "dateTime": "2026-05-14T12:54:54.000Z",
        "market": {
          "id": "328605106538185774745222214510554688292908224634694168900-3156615923078993896613747117076284775081499773140419317205",
          "baseToken": "0xdf69970b2fe416339187aa41d39882e864984ce9",
          "quoteToken": "0xa338b743ec494ebb8345f4b6f27ffc902b7ef5aa"
        }
      }
    ]
  },
  "timestamp": "2026-07-12T06:15:00.000Z"
}

Integration Example (Axios)

Node.js Integration Code

const axios = require('axios');

async function verifyOrderbookQuest(userAddress, tokenAddress, minSwapsRequired = 1) {
  try {
    const url = `${window.location.origin}/api/orderbook-verify-swaps`;
    const response = await axios.get(url, {
      params: {
        address: userAddress,
        token: tokenAddress,
        minSwaps: minSwapsRequired,
        counterToken: '0x0000000000000000000000000000000000000000' // verify swaps specifically against zkLTC
      }
    });

    const { success, verification } = response.data;
    if (success) {
      console.log(`User completed orderbook swaps: ${verification.totalSwaps}`);
      console.log(`Eligible for Quest: ${verification.isEligible ? 'YES' : 'NO'}`);
      return verification.isEligible;
    }
    return false;
  } catch (error) {
    console.error('Quest verification failed:', error.message);
    return false;
  }
}