Fees API

Query fee data including transaction-level fees, daily statistics, and protocol/trader summaries.

Table of Contents

• Queries

  • feeTransaction

  • feeTransactions

  • feeDailyStats

  • feeAnalytics

  • protocolFeeSummary

  • traderFeeSummary

• Types Reference

Queries

feeTransaction

Get a specific fee transaction by ID.

Signature:

feeTransaction(id: ID!): FeeTransaction

Parameters:

• id: Transaction ID (string)

Returns: FeeTransaction object or null

Example:

query GetFeeTransaction {
  fee {
    feeTransaction(id: "abc123") {
      id
      traderAddress
      feeType
      totalFeeCharged
      govFee
      vaultFee
      referrerAllocation
      triggerFee
      collateralDenom
      blockHeight
      blockTime
    }
  }
}

---

feeTransactions

List fee transactions with filtering and pagination.

Signature:

feeTransactions(
  filter: FeeTransactionFilter
  limit: Int = 100
  offset: Int = 0
): [FeeTransaction!]!

Parameters:

• filter: Filter object (optional)

  • traderAddress: Filter by trader

  • collateralDenom: Filter by collateral token

  • feeType: Filter by OPENING or CLOSING

  • fromDate: Start date (RFC3339)

  • toDate: End date (RFC3339)

  • minAmount: Minimum fee amount

  • maxAmount: Maximum fee amount

• limit: Max results (default: 100)

• offset: Skip results (default: 0)

Returns: Array of FeeTransaction objects

Example - Get User Fees:

query GetUserFees($trader: String!) {
  fee {
    feeTransactions(
      filter: { traderAddress: $trader }
      limit: 50
    ) {
      id
      feeType
      totalFeeCharged
      govFee
      vaultFee
      referrerAllocation
      triggerFee
      blockTime
      tradeId
      orderType
    }
  }
}

Example - Filter by Date Range:

query GetFeesInRange {
  fee {
    feeTransactions(
      filter: {
        fromDate: "2024-01-01T00:00:00Z"
        toDate: "2024-01-31T23:59:59Z"
        feeType: OPENING
      }
      limit: 100
    ) {
      id
      traderAddress
      totalFeeCharged
      blockTime
    }
  }
}

Example - Large Fees Only:

query GetLargeFees {
  fee {
    feeTransactions(
      filter: {
        minAmount: 1000000  # Filter fees > 1,000,000
      }
      limit: 20
    ) {
      id
      traderAddress
      totalFeeCharged
      feeType
    }
  }
}

Use Cases:

• User fee history

• Protocol fee monitoring

• Large transaction tracking

• Fee analysis by period

---

feeDailyStats

Get aggregated daily fee statistics.

Signature:

feeDailyStats(
  filter: FeeDailyStatsFilter
  limit: Int = 30
  offset: Int = 0
): [FeeDailyStats!]!

Parameters:

• filter: Filter object (optional)

  • traderAddress: Filter by specific trader

  • collateralDenom: Filter by collateral token

  • fromDate: Start date

  • toDate: End date

  • protocolWide: If true, get protocol-wide stats

• limit: Max results (default: 30)

• offset: Skip results (default: 0)

Returns: Array of FeeDailyStats objects

Example - Protocol Daily Stats:

query GetProtocolDailyStats {
  fee {
    feeDailyStats(
      filter: { protocolWide: true }
      limit: 30
    ) {
      date
      collateralDenom
      openingFeeCount
      openingFeeTotal
      openingGovFee
      openingReferrerFee
      openingVaultFee
      closingFeeCount
      closingFeeTotal
      closingGovFee
      closingReferrerFee
      closingVaultFee
      closingTriggerFee
      totalBadDebt
      updatedAt
    }
  }
}

Example - Trader Daily Stats:

query GetTraderDailyStats($trader: String!) {
  fee {
    feeDailyStats(
      filter: {
        traderAddress: $trader
        fromDate: "2024-01-01T00:00:00Z"
      }
      limit: 90
    ) {
      date
      openingFeeTotal
      closingFeeTotal
      totalBadDebt
    }
  }
}

Use Cases:

• Daily fee charts

• Historical fee analysis

• Revenue tracking

• Trader fee breakdown

---

feeAnalytics

Get enhanced fee analytics with additional metrics.

Signature:

feeAnalytics(
  filter: FeeDailyStatsFilter
  limit: Int = 30
  offset: Int = 0
): [FeeAnalytics!]!

Parameters: Same as feeDailyStats

Returns: Array of FeeAnalytics objects

Example:

query GetFeeAnalytics {
  fee {
    feeAnalytics(
      filter: { protocolWide: true }
      limit: 30
    ) {
      date
      collateralDenom
      openingCount
      openingTotal
      openingGov
      openingReferrer
      openingVault
      openingTrigger
      closingCount
      closingTotal
      closingGov
      closingReferrer
      closingVault
      closingTrigger
      totalFeesAll
      avgFeeMultiplier
      totalBadDebt
      traderAddress
    }
  }
}

Key Differences from feeDailyStats:

• Includes avgFeeMultiplier

• Includes totalFeesAll (sum of opening + closing)

• More granular trigger fee breakdown

Use Cases:

• Advanced analytics dashboards

• Fee multiplier tracking

• Comprehensive fee reports

---

protocolFeeSummary

Get protocol-wide fee summary for a time period.

Signature:

protocolFeeSummary(
  collateralDenom: String
  fromDate: Time
  toDate: Time
): ProtocolFeeSummary!

Parameters:

• collateralDenom: Optional collateral filter

• fromDate: Start date (optional)

• toDate: End date (optional)

Returns: ProtocolFeeSummary object

Example - All-Time Protocol Summary:

query GetProtocolSummary {
  fee {
    protocolFeeSummary {
      period {
        fromDate
        toDate
      }
      totalFees
      totalOpeningFees
      totalClosingFees
      totalGovFees
      totalVaultFees
      totalReferrerFees
      totalTriggerFees
      totalBadDebt
      openingCount
      closingCount
      uniqueTraders
      avgFeeMultiplier
    }
  }
}

Example - Monthly Summary:

query GetMonthlySummary {
  fee {
    protocolFeeSummary(
      fromDate: "2024-01-01T00:00:00Z"
      toDate: "2024-01-31T23:59:59Z"
    ) {
      totalFees
      totalOpeningFees
      totalClosingFees
      uniqueTraders
      openingCount
      closingCount
    }
  }
}

Example - Per-Collateral Summary:

query GetCollateralSummary {
  fee {
    protocolFeeSummary(
      collateralDenom: "uusdc"
      fromDate: "2024-01-01T00:00:00Z"
    ) {
      totalFees
      totalVaultFees
      totalGovFees
      uniqueTraders
    }
  }
}

Use Cases:

• Protocol revenue reports

• KPI tracking

• Performance metrics

• Time-period comparisons

---

traderFeeSummary

Get fee summary for a specific trader.

Signature:

traderFeeSummary(
  traderAddress: String!
  collateralDenom: String
  fromDate: Time
  toDate: Time
): TraderFeeSummary!

Parameters:

• traderAddress: Trader's address (required)

• collateralDenom: Optional collateral filter

• fromDate: Start date (optional)

• toDate: End date (optional)

Returns: TraderFeeSummary object

Example - All-Time Trader Summary:

query GetTraderSummary($trader: String!) {
  fee {
    traderFeeSummary(traderAddress: $trader) {
      traderAddress
      period {
        fromDate
        toDate
      }
      totalFees
      totalOpeningFees
      totalClosingFees
      totalReferrerAllocation
      totalBadDebt
      openingCount
      closingCount
      avgFeeMultiplier
    }
  }
}

Example - Monthly Trader Summary:

query GetTraderMonthlySummary($trader: String!) {
  fee {
    traderFeeSummary(
      traderAddress: $trader
      fromDate: "2024-01-01T00:00:00Z"
      toDate: "2024-01-31T23:59:59Z"
    ) {
      totalFees
      openingCount
      closingCount
      avgFeeMultiplier
    }
  }
}

Use Cases:

• User dashboards

• Trading cost analysis

• Fee optimization insights

• Referral tracking

---

Types Reference

FeeTransaction

Complete fee transaction details.

type FeeTransaction {
  id: ID!
  traderAddress: String!
  tradeId: Int!
  tradeIndex: Int!
  feeType: FeeType!
  collateralDenom: String!
  totalFeeCharged: Int!
  govFee: Int!
  netGovFee: Int!
  vaultFee: Int!
  referrerAllocation: Int!
  triggerFee: Int!
  openFeeComponent: Int
  triggerFeeComponent: Int
  triggererReward: Int
  collateralLeft: Int
  badDebt: Int!
  feeMultiplier: Float!
  orderType: String
  catalystAddress: String
  blockHeight: Int!
  blockTime: Time!
  createdAt: Time!
}

Key Fields:

• totalFeeCharged: Total fee paid by trader

• govFee: Fee to protocol governance

• vaultFee: Fee to LP vault

• referrerAllocation: Fee to referrer (if any)

• triggerFee: Fee paid to order trigger executor

• badDebt: Bad debt if position liquidated with insufficient collateral

• feeMultiplier: Dynamic fee multiplier applied

---

FeeDailyStats

Daily aggregated fee statistics.

type FeeDailyStats {
  date: Time!
  collateralDenom: String!
  traderAddress: String
  openingFeeCount: Int!
  openingFeeTotal: Int!
  openingGovFee: Int!
  openingReferrerFee: Int!
  openingTriggerFee: Int!
  openingVaultFee: Int!
  closingFeeCount: Int!
  closingFeeTotal: Int!
  closingGovFee: Int!
  closingReferrerFee: Int!
  closingTriggerFee: Int!
  closingVaultFee: Int!
  totalBadDebt: Int!
  updatedAt: Time!
}

---

FeeAnalytics

Enhanced analytics with additional metrics.

type FeeAnalytics {
  date: Time!
  collateralDenom: String!
  traderAddress: String
  openingCount: Int!
  openingTotal: Int!
  openingGov: Int!
  openingReferrer: Int!
  openingTrigger: Int!
  openingVault: Int!
  closingCount: Int!
  closingTotal: Int!
  closingGov: Int!
  closingReferrer: Int!
  closingTrigger: Int!
  closingVault: Int!
  totalFeesAll: Int!
  avgFeeMultiplier: Float!
  totalBadDebt: Int!
}

---

ProtocolFeeSummary

Protocol-wide fee summary.

type ProtocolFeeSummary {
  period: TimePeriod!
  totalFees: Int!
  totalOpeningFees: Int!
  totalClosingFees: Int!
  totalGovFees: Int!
  totalVaultFees: Int!
  totalReferrerFees: Int!
  totalTriggerFees: Int!
  totalBadDebt: Int!
  openingCount: Int!
  closingCount: Int!
  uniqueTraders: Int!
  avgFeeMultiplier: Float!
}

---

TraderFeeSummary

Per-trader fee summary.

type TraderFeeSummary {
  traderAddress: String!
  period: TimePeriod!
  totalFees: Int!
  totalOpeningFees: Int!
  totalClosingFees: Int!
  totalReferrerAllocation: Int!
  totalBadDebt: Int!
  openingCount: Int!
  closingCount: Int!
  avgFeeMultiplier: Float!
}

---

Enums

FeeType:

• OPENING: Fees charged when opening positions

• CLOSING: Fees charged when closing positions

---

Fee Calculations

Total Protocol Revenue

const totalRevenue = protocolFeeSummary.totalGovFees + 
                     protocolFeeSummary.totalVaultFees

Average Fee Per Trade

const avgOpeningFee = protocolFeeSummary.totalOpeningFees / 
                      protocolFeeSummary.openingCount

const avgClosingFee = protocolFeeSummary.totalClosingFees / 
                      protocolFeeSummary.closingCount

Fee Breakdown Percentages

const calculateBreakdown = (summary) => {
  const total = summary.totalFees
  return {
    govPct: (summary.totalGovFees / total) * 100,
    vaultPct: (summary.totalVaultFees / total) * 100,
    referrerPct: (summary.totalReferrerFees / total) * 100,
    triggerPct: (summary.totalTriggerFees / total) * 100
  }
}

Convert Fee Amounts

// Fees are in smallest unit, convert to decimal
const convertFee = (feeAmount, decimals) => {
  return feeAmount / (10 ** decimals)
}

// Example: USDC fees (6 decimals)
const feeUSDC = convertFee(1000000, 6) // = 1.0 USDC

---

Best Practices

Date Range Queries

// Get current month stats
const now = new Date()
const firstDay = new Date(now.getFullYear(), now.getMonth(), 1)
const lastDay = new Date(now.getFullYear(), now.getMonth() + 1, 0)

const query = `
  query GetMonthlyStats {
    fee {
      protocolFeeSummary(
        fromDate: "${firstDay.toISOString()}"
        toDate: "${lastDay.toISOString()}"
      ) {
        totalFees
        uniqueTraders
      }
    }
  }
`

Pagination for Large Datasets

// Fetch all fee transactions in batches
const fetchAllFees = async (trader, limit = 100) => {
  let allFees = []
  let offset = 0
  let hasMore = true
  
  while (hasMore) {
    const { data } = await client.query({
      query: FEE_TRANSACTIONS_QUERY,
      variables: { trader, limit, offset }
    })
    
    const fees = data.fee.feeTransactions
    allFees = allFees.concat(fees)
    
    hasMore = fees.length === limit
    offset += limit
  }
  
  return allFees
}

Caching Daily Stats

// Cache daily stats (they don't change)
const cacheDailyStats = new Map()

const getDailyStats = async (date) => {
  const dateKey = date.toISOString().split('T')[0]
  
  if (cacheDailyStats.has(dateKey)) {
    return cacheDailyStats.get(dateKey)
  }
  
  const stats = await fetchDailyStats(date)
  cacheDailyStats.set(dateKey, stats)
  return stats
}