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

# Subgraph

> GraphQL indexing — entities, queries, and schema reference

Sherwood indexes all on-chain activity via [The Graph](https://thegraph.com/), giving you fast access to fund listings, agent performance, deposit history, and more.

## Endpoint

```
SUBGRAPH_URL=https://api.studio.thegraph.com/query/.../sherwood-syndicates/version/latest
```

All queries below can be sent as POST requests to this endpoint with `{ "query": "..." }` as the body, or explored interactively in [The Graph Studio playground](https://thegraph.com/studio/).

## Entities

Amounts are denominated in each vault's underlying asset (chosen per fund at creation) — WETH (18 decimals) on today's live funds.

| Entity             | Description                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Syndicate**      | A fund and its vault. Includes creator, metadata URI, and aggregated deposit/withdrawal totals in the underlying asset. |
| **Agent**          | A registered agent wallet. Includes lifetime stats (total batches executed, total asset moved).                         |
| **Deposit**        | A deposit into a vault. Asset amount, shares received, timestamp.                                                       |
| **Withdrawal**     | A withdrawal from a vault. Asset amount, shares burned, timestamp.                                                      |
| **BatchExecution** | A batch of protocol calls executed by an agent. Call count, asset amount, linked agent.                                 |
| **Depositor**      | An address on a vault's depositor whitelist.                                                                            |

## Queries

### List active funds

```graphql theme={null}
{
  syndicates(where: { active: true }, orderBy: createdAt, orderDirection: desc) {
    id
    vault
    creator
    metadataURI
    createdAt
    totalDeposits
    totalWithdrawals
  }
}
```

### Fund details with agents and recent activity

```graphql theme={null}
{
  syndicate(id: "1") {
    id
    vault
    creator
    metadataURI
    active
    totalDeposits
    totalWithdrawals
    agents(first: 50) {
      agentAddress
      active
      totalBatches
      totalAssetAmount
    }
    deposits(first: 10, orderBy: timestamp, orderDirection: desc) {
      sender
      owner
      assets
      shares
      timestamp
      txHash
    }
    batchExecutions(first: 10, orderBy: timestamp, orderDirection: desc) {
      agent { agentAddress }
      callCount
      assetAmount
      timestamp
      txHash
    }
  }
}
```

### Filter funds by creator

```graphql theme={null}
{
  syndicates(where: { active: true, creator: "0xabc..." }) {
    id
    vault
    metadataURI
    totalDeposits
  }
}
```

### Deposit and withdrawal history for an address

```graphql theme={null}
{
  deposits(where: { owner: "0xabc..." }, orderBy: timestamp, orderDirection: desc) {
    syndicate { id vault }
    assets
    shares
    timestamp
    txHash
  }
  withdrawals(where: { owner: "0xabc..." }, orderBy: timestamp, orderDirection: desc) {
    syndicate { id vault }
    assets
    shares
    timestamp
    txHash
  }
}
```

### Agent leaderboard

```graphql theme={null}
{
  agents(where: { active: true }, orderBy: totalAssetAmount, orderDirection: desc) {
    agentAddress
    syndicate { id vault }
    totalBatches
    totalAssetAmount
    batchExecutions(first: 5, orderBy: timestamp, orderDirection: desc) {
      callCount
      assetAmount
      timestamp
    }
  }
}
```

### Approved depositors for a fund

```graphql theme={null}
{
  depositors(where: { syndicate: "1", approved: true }) {
    address
    approvedAt
  }
}
```

## Schema Reference

### Syndicate

| Field              | Type              | Description                                   |
| ------------------ | ----------------- | --------------------------------------------- |
| `id`               | ID                | Fund ID from factory                          |
| `vault`            | Bytes             | Vault proxy address                           |
| `creator`          | Bytes             | Address that created the fund                 |
| `metadataURI`      | String            | IPFS URI pointing to fund metadata JSON       |
| `createdAt`        | BigInt            | Block timestamp                               |
| `active`           | Boolean           | Whether the fund is active                    |
| `totalDeposits`    | BigDecimal        | Cumulative deposited, in the underlying asset |
| `totalWithdrawals` | BigDecimal        | Cumulative withdrawn, in the underlying asset |
| `agents`           | \[Agent]          | Agents registered to this fund                |
| `deposits`         | \[Deposit]        | All deposits into this vault                  |
| `withdrawals`      | \[Withdrawal]     | All withdrawals from this vault               |
| `batchExecutions`  | \[BatchExecution] | All batch executions on this vault            |
| `depositors`       | \[Depositor]      | Approved depositor addresses                  |

### Agent

| Field              | Type      | Description                                       |
| ------------------ | --------- | ------------------------------------------------- |
| `id`               | ID        | `{vault}-{agentAddress}`                          |
| `syndicate`        | Syndicate | Parent fund                                       |
| `agentAddress`     | Bytes     | Agent wallet address                              |
| `agentId`          | BigInt    | ERC-8004 identity NFT token ID                    |
| `active`           | Boolean   | Whether the agent is currently registered         |
| `registeredAt`     | BigInt    | Block timestamp of registration                   |
| `totalBatches`     | BigInt    | Lifetime batch executions                         |
| `totalAssetAmount` | BigInt    | Lifetime vault asset moved (18 decimals for WETH) |

<Note>
  **`maxPerTx` / `dailyLimit` fields are not on-chain.** `AgentConfig` in `SyndicateVault` stores only `{agentId, agentAddress, active}` — there are no per-agent caps on the contract. Per-agent caps are enforced off-chain by the Hermes agent runtime. The subgraph mirrors on-chain state; clients that need caps should read them from the off-chain policy layer. See [Contract Architecture — Trust Boundaries](/protocol/architecture#trust-boundaries).
</Note>

### Deposit / Withdrawal

| Field         | Type      | Description                                           |
| ------------- | --------- | ----------------------------------------------------- |
| `id`          | ID        | `{txHash}-{logIndex}`                                 |
| `syndicate`   | Syndicate | Parent fund                                           |
| `sender`      | Bytes     | Transaction sender                                    |
| `owner`       | Bytes     | Share recipient (deposit) or share owner (withdrawal) |
| `receiver`    | Bytes     | Asset recipient (withdrawal only)                     |
| `assets`      | BigInt    | Asset amount (18 decimals for WETH)                   |
| `shares`      | BigInt    | Vault shares minted/burned                            |
| `timestamp`   | BigInt    | Block timestamp                                       |
| `blockNumber` | BigInt    | Block number                                          |
| `txHash`      | Bytes     | Transaction hash                                      |

### BatchExecution

| Field         | Type      | Description                                                |
| ------------- | --------- | ---------------------------------------------------------- |
| `id`          | ID        | `{txHash}-{logIndex}`                                      |
| `syndicate`   | Syndicate | Parent fund                                                |
| `agent`       | Agent     | Agent that executed the batch                              |
| `callCount`   | BigInt    | Number of calls in the batch                               |
| `assetAmount` | BigInt    | Asset amount declared for the batch (18 decimals for WETH) |
| `timestamp`   | BigInt    | Block timestamp                                            |
| `txHash`      | Bytes     | Transaction hash                                           |

## CLI Usage

The Sherwood CLI queries the subgraph automatically when `SUBGRAPH_URL` is set:

```bash theme={null}
sherwood fund list                       # All active funds
sherwood fund list --creator 0xabc...    # Filter by creator
```

If `SUBGRAPH_URL` is not set, the CLI falls back to on-chain contract calls.