コンテンツにスキップ
Sai

Fee API Reference

このコンテンツはまだ日本語訳がありません。

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

Table of Contents

Section titled “Table of Contents”

Queries

Section titled “Queries”

feeTransaction

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Types Reference”

FeeTransaction

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Enums”

FeeType:

  • OPENING: Fees charged when opening positions
  • CLOSING: Fees charged when closing positions

Fee Calculations

Section titled “Fee Calculations”

Total Protocol Revenue

Section titled “Total Protocol Revenue”
const totalRevenue = protocolFeeSummary.totalGovFees +
                     protocolFeeSummary.totalVaultFees

Average Fee Per Trade

Section titled “Average Fee Per Trade”
const avgOpeningFee = protocolFeeSummary.totalOpeningFees /
                      protocolFeeSummary.openingCount


const avgClosingFee = protocolFeeSummary.totalClosingFees /
                      protocolFeeSummary.closingCount

Fee Breakdown Percentages

Section titled “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

Section titled “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

Section titled “Best Practices”

Date Range Queries

Section titled “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

Section titled “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

Section titled “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
}