# API reference

An index of the Noderr APIs, with shared rules for authentication, rate limits and errors.

> **Planned.** Examples that use `api.noderr.xyz` describe the planned public API, which is not yet live. The live API is `https://agent.noderr.xyz`. See the [Agent Protocol API Reference](../for-ai-agents/api-reference.md).

## Available APIs

| API | Purpose | Documentation |
|-----|---------|---------------|
| REST API | Standard HTTP endpoints | [REST API Reference](../api/rest-api.md) |
| WebSocket API | Real-time streaming | [WebSocket API Reference](../api/websocket-api.md) |
| GraphQL API | Flexible queries | [GraphQL API Reference](../api/graphql-api.md) |

## Base URLs

| Environment | Base URL |
|-------------|----------|
| Testnet | `https://api-testnet.noderr.xyz/v1` |
| Mainnet | `https://api.noderr.xyz/v1` |

## Quick start

### REST

```bash
# Get all vaults
curl https://api.noderr.xyz/v1/vaults

# Get specific vault
curl https://api.noderr.xyz/v1/vaults/0x49f747BBac988Cd628a5D79AAdF865EBaDe6a34f
```

### WebSocket

```javascript
const ws = new WebSocket('wss://ws.noderr.xyz/v1');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'vault.updates',
    params: { address: '0x49f747BBac988Cd628a5D79AAdF865EBaDe6a34f' }
  }));
};
```

### GraphQL

```graphql
query {
  vaults {
    address
    name
    tvlUsd
    apy { current }
  }
}
```

## Authentication

Most read endpoints are public and need no authentication. Write operations need a wallet signature:

```javascript
const message = `Noderr API Access\nTimestamp: ${Date.now()}`;
const signature = await wallet.signMessage(message);

fetch('https://api.noderr.xyz/v1/user/settings', {
  method: 'POST',
  headers: {
    'X-Wallet-Address': walletAddress,
    'X-Signature': signature,
    'X-Timestamp': timestamp
  },
  body: JSON.stringify(settings)
});
```

## Rate limits

| Tier | Requests/Minute | Requests/Day |
|------|-----------------|--------------|
| Public | 60 | 10,000 |
| Authenticated | 300 | 100,000 |
| Node Operator | 1,000 | Unlimited |

## Error codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INVALID_ADDRESS` | 400 | Invalid Ethereum address |
| `VAULT_NOT_FOUND` | 404 | Vault does not exist |
| `STRATEGY_NOT_FOUND` | 404 | Strategy does not exist |
| `UNAUTHORIZED` | 401 | Invalid or missing authentication |
| `RATE_LIMITED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Server error |

## SDK

The `@noderr/sdk` package is planned and not yet published. See the [SDK Reference](./sdk-reference.md).

```bash
npm install @noderr/sdk
```

*Last updated: June 2026*