# GraphQL API Reference

> **Note:** The `api.noderr.xyz` public REST/GraphQL/WebSocket API is not yet live. This page documents the planned interface. For the currently live API, see the [Agent Protocol API Reference](../for-ai-agents/api-reference.md) at `https://agent.noderr.xyz`.

The Noderr Protocol GraphQL API provides flexible querying capabilities for complex data requirements.

## Endpoint

```
https://api.noderr.xyz/graphql
```

For testnet:
```
https://api-testnet.noderr.xyz/graphql
```

## Schema

### Types

```graphql
type Vault {
  address: String!
  name: String!
  symbol: String!
  tvl: BigInt!
  tvlUsd: Float!
  totalShares: BigInt!
  pricePerShare: BigInt!
  apy: APY!
  fees: Fees!
  riskLevel: RiskLevel!
  strategies: [Strategy!]!
  isERC7540: Boolean!
  fulfillmentDelay: Int
  createdAt: DateTime!
}

type APY {
  current: Float!
  day7: Float!
  day30: Float!
  inception: Float!
}

type Fees {
  management: Float!
  performance: Float!
  hurdle: Float!
}

type Strategy {
  id: ID!
  name: String!
  status: StrategyStatus!
  allocation: Float!
  apy: Float!
  riskScore: Int!
  sharpeRatio: Float!
  maxDrawdown: Float!
}

type UserPosition {
  vault: Vault!
  shares: BigInt!
  value: BigInt!
  pnl: BigInt!
  pnlPercent: Float!
  depositedAt: DateTime!
}

type Transaction {
  hash: String!
  type: TransactionType!
  vault: Vault!
  user: String!
  amount: BigInt!
  shares: BigInt
  status: TransactionStatus!
  timestamp: DateTime!
}

enum RiskLevel {
  CONSERVATIVE
  MODERATE
  AGGRESSIVE
}

enum StrategyStatus {
  EVOLUTION
  SHADOW
  LIVE
  DEPRECATED
}

enum TransactionType {
  DEPOSIT
  WITHDRAW
  DEPOSIT_REQUEST
  REDEEM_REQUEST
  CLAIM
}

enum TransactionStatus {
  PENDING
  FULFILLED
  CLAIMED
  FAILED
}
```

### Queries

```graphql
type Query {
  # Vaults
  vaults(
    riskLevel: RiskLevel
    minTvl: BigInt
    orderBy: VaultOrderBy
  ): [Vault!]!
  
  vault(address: String!): Vault
  
  vaultHistory(
    address: String!
    period: Period!
    interval: Interval!
  ): [VaultSnapshot!]!
  
  # Strategies
  strategies(
    status: StrategyStatus
    minSharpe: Float
  ): [Strategy!]!
  
  strategy(id: ID!): Strategy
  
  # User data
  userPositions(address: String!): [UserPosition!]!
  
  userTransactions(
    address: String!
    type: TransactionType
    limit: Int
    offset: Int
  ): [Transaction!]!
  
  # Protocol
  protocolStats: ProtocolStats!
  
  # Nodes
  nodeStats: NodeStats!
}
```

## Example Queries

### Get All Vaults with Strategies

```graphql
query GetVaults {
  vaults(orderBy: TVL_DESC) {
    address
    name
    symbol
    tvlUsd
    apy {
      current
      day30
    }
    riskLevel
    strategies {
      name
      allocation
      apy
    }
  }
}
```

### Get User Portfolio

```graphql
query GetUserPortfolio($address: String!) {
  userPositions(address: $address) {
    vault {
      name
      symbol
      apy {
        current
      }
    }
    shares
    value
    pnl
    pnlPercent
  }
}
```

### Get Vault with History

```graphql
query GetVaultDetails($address: String!) {
  vault(address: $address) {
    name
    tvlUsd
    apy {
      current
      day7
      day30
      inception
    }
    fees {
      management
      performance
      hurdle
    }
    isERC7540
    fulfillmentDelay
  }
  
  vaultHistory(
    address: $address
    period: MONTH
    interval: DAY
  ) {
    timestamp
    tvl
    apy
    pricePerShare
  }
}
```

## Subscriptions

Real-time updates via GraphQL subscriptions:

```graphql
subscription OnVaultUpdate($address: String!) {
  vaultUpdated(address: $address) {
    tvl
    pricePerShare
    apy {
      current
    }
  }
}

subscription OnNewTransaction($vaultAddress: String) {
  transactionCreated(vaultAddress: $vaultAddress) {
    hash
    type
    amount
    user
    timestamp
  }
}
```

## Pagination

Use cursor-based pagination for large result sets:

```graphql
query GetTransactions($cursor: String) {
  userTransactions(
    address: "0x..."
    first: 20
    after: $cursor
  ) {
    edges {
      node {
        hash
        type
        amount
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Error Handling

GraphQL errors follow the standard format:

```json
{
  "errors": [
    {
      "message": "Vault not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["vault"],
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}
```

---

*Last Updated: December 2025*