# REST 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 REST API provides programmatic access to vault data, strategy information, and protocol metrics. All endpoints are publicly accessible and require no authentication for read operations.

## Base URL

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

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

## Authentication

Read endpoints are public and require no authentication. Write operations require a signed message from a connected wallet.

## Rate Limits

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

## Endpoints

### Vaults

#### Get All Vaults

```http
GET /vaults
```

Returns a list of all active vaults with current metrics.

**Response:**
```json
{
  "vaults": [
    {
      "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84",
      "name": "Conservative Vault",
      "symbol": "nCONS",
      "tvl": "1250000000000000000000",
      "tvlUsd": 1250000.00,
      "apy": 8.5,
      "riskLevel": "conservative",
      "strategies": 3,
      "isERC7540": true,
      "fulfillmentDelay": 3600
    }
  ],
  "totalTvl": "5000000000000000000000",
  "totalTvlUsd": 5000000.00
}
```

#### Get Vault Details

```http
GET /vaults/:address
```

Returns detailed information about a specific vault.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| address | string | Vault contract address |

**Response:**
```json
{
  "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84",
  "name": "Conservative Vault",
  "symbol": "nCONS",
  "asset": "0x...",
  "tvl": "1250000000000000000000",
  "totalShares": "1200000000000000000000",
  "pricePerShare": "1041666666666666666",
  "apy": {
    "current": 8.5,
    "7d": 8.2,
    "30d": 8.7,
    "inception": 9.1
  },
  "fees": {
    "management": 0,
    "performance": 20,
    "hurdle": 8
  },
  "strategies": [
    {
      "name": "Aave USDC Lending",
      "allocation": 40,
      "apy": 5.2
    }
  ],
  "isERC7540": true,
  "fulfillmentDelay": 3600
}
```

#### Get Vault History

```http
GET /vaults/:address/history
```

Returns historical TVL and APY data for a vault.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| period | string | 30d | Time period (7d, 30d, 90d, 1y, all) |
| interval | string | 1d | Data interval (1h, 4h, 1d, 1w) |

### Strategies

#### Get All Strategies

```http
GET /strategies
```

Returns all active trading strategies.

#### Get Strategy Performance

```http
GET /strategies/:id/performance
```

Returns detailed performance metrics for a strategy.

### Nodes

#### Get Node Status

```http
GET /nodes
```

Returns status of all registered nodes in the network.

### User Data

#### Get User Positions

```http
GET /users/:address/positions
```

Returns all vault positions for a user.

#### Get User Transactions

```http
GET /users/:address/transactions
```

Returns transaction history for a user.

### Protocol Metrics

#### Get Protocol Stats

```http
GET /protocol/stats
```

Returns aggregate protocol statistics.

## Error Handling

All errors follow a consistent format:

```json
{
  "error": {
    "code": "VAULT_NOT_FOUND",
    "message": "Vault with address 0x... not found",
    "details": {}
  }
}
```

**Common Error Codes:**
| Code | HTTP Status | Description |
|------|-------------|-------------|
| VAULT_NOT_FOUND | 404 | Vault does not exist |
| INVALID_ADDRESS | 400 | Invalid Ethereum address |
| RATE_LIMITED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Server error |

## SDK Integration

For easier integration, use our official SDKs:

- [JavaScript/TypeScript SDK](../developers/sdk-reference.md)
- [Python SDK](https://github.com/Noderrxyz/noderr-python-sdk)

---

*Last Updated: December 2025*