> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nilemarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subgraph Overview

> The Graph subgraph indexing six onchain data sources (PositionManager, SettlementEngine, PoolVault, MarginAccounts, OracleModule, ModeController) into 14 GraphQL entities for historical queries, analytics, and event-driven data

The FX Forward Protocol subgraph indexes all onchain events into a queryable GraphQL API. It powers historical position data, pool analytics, oracle price history, and protocol state tracking that would be expensive or impossible to retrieve via direct RPC calls.

## GraphQL Endpoint

<Tabs>
  <Tab title="Local (Graph Node)">
    ```
    http://localhost:8000/subgraphs/name/fx-forward
    ```

    Run via `docker compose` with the local Graph Node stack.
  </Tab>

  <Tab title="Sepolia (Subgraph Studio)">
    ```
    https://api.studio.thegraph.com/query/<SUBGRAPH_ID>/fx-forward/version/latest
    ```

    Contact the team for the current Sepolia deployment ID.
  </Tab>
</Tabs>

## Indexed Data Sources

The subgraph listens to events from six contracts:

| Data Source      | Events Indexed                                                                                                                     | Entities Updated                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| PositionManager  | `PositionOpened`, `PositionIncreased`, `PositionClosed`, `TradingFeeCollected`, `OracleFeeCollected`                               | Position, Account, PoolState, PoolTransaction           |
| SettlementEngine | `PositionSettledAtMaturity`, `PositionLiquidated`, `PositionClosedEarly`, `PositionReduced`, `FeesCollected`, `OracleFeeCollected` | Position, PoolState, PositionReduction, PoolTransaction |
| PoolVault        | `Deposit`, `Withdraw`, `PnlApplied`, `ExposureUpdated`                                                                             | PoolState, Account, VaultEvent                          |
| MarginAccounts   | `CollateralDeposited`, `CollateralWithdrawn`, `MarginLocked`, `MarginUnlocked`, `PnlSettled`, `BadDebt`                            | Account                                                 |
| OracleModule     | `ForwardRoundPublished`, `FixingPriceRecorded`                                                                                     | OracleRound, FixingPrice                                |
| ModeController   | `ModeTransition`                                                                                                                   | ModeTransition, ProtocolState                           |

## Entity Overview

Thirteen entity types fall into three categories:

### Mutable State Entities

Updated as new events arrive. Use these for current-state queries.

| Entity                                                | ID Pattern               | Description                  |
| ----------------------------------------------------- | ------------------------ | ---------------------------- |
| [Position](/build/subgraph-schema#position)           | `positionId`             | Full position lifecycle data |
| [Account](/build/subgraph-schema#account)             | `address`                | Trader margin and LP state   |
| [PoolState](/build/subgraph-schema#poolstate)         | `"pool"` (singleton)     | Pool assets, exposure, fees  |
| [ProtocolState](/build/subgraph-schema#protocolstate) | `"protocol"` (singleton) | Current operating mode       |
| [DailyStats](/build/subgraph-schema#dailystats)       | Unix day number          | Daily aggregate analytics    |

### Immutable Event Records

Append-only, never updated after creation. Optimized for write performance.

| Entity                                                        | ID Pattern                | Description                   |
| ------------------------------------------------------------- | ------------------------- | ----------------------------- |
| [OracleRound](/build/subgraph-schema#oracleround)             | `fixingTimestamp-roundId` | Forward price rounds          |
| [FixingPrice](/build/subgraph-schema#fixingprice)             | `pairId-fixingTimestamp`  | Settlement fixing prices      |
| [FeeEvent](/build/subgraph-schema#feeevent)                   | `txHash-logIndex`         | Fee collection events         |
| [PositionReduction](/build/subgraph-schema#positionreduction) | `txHash-logIndex`         | Partial reduction records     |
| [VaultEvent](/build/subgraph-schema#vaultevent)               | `txHash-logIndex`         | LP deposit/withdraw history   |
| [PoolTransaction](/build/subgraph-schema#pooltransaction)     | `txHash-logIndex`         | Unified activity feed         |
| [ModeTransition](/build/subgraph-schema#modetransition)       | `txHash-logIndex`         | Mode state change audit trail |

### Internal Helper

| Entity           | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| TxFeeAccumulator | Links fee events to pool transactions within a single tx. Not queried directly. |

## Design Principles

**Event-driven only** -- the subgraph uses no block handlers or call handlers. All data comes from emitted events, keeping indexing fast and deterministic.

**No eth\_calls** -- handler code never calls contract functions. Every data point is derived from event parameters, avoiding RPC round-trips during indexing.

**Immutable optimization** -- append-only entities use `@entity(immutable: true)`, skipping block-range versioning and reducing write amplification by 2-3x.

## Related Pages

<Columns cols={3}>
  <Card title="Schema Reference" icon="database" href="/build/subgraph-schema">
    Complete entity and field definitions.
  </Card>

  <Card title="Query Examples" icon="magnifying-glass" href="/build/subgraph-queries">
    Common GraphQL query patterns.
  </Card>

  <Card title="Data Source Guide" icon="diagram-project" href="/build/subgraph-data-source">
    When to use subgraph vs RPC.
  </Card>
</Columns>