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

# Requests

> How to structure API requests with query parameters

The API uses a JSON-based query language passed as a URL parameter named `query`. The query object can include:

* `filter` - Filter conditions
* `sort` - Sort configuration
* `pagination` - Pagination settings
* `aggregate` - Aggregation configuration (for aggregate endpoints)

Every endpoint has a corresponding [`/meta` endpoint](/api/meta) that returns the available fields, allowed operators, and valid values.

## Basic Example

```json theme={null}
{
  "filter": {
    "operator": "equals",
    "field": "protocol_slug",
    "value": "ondo"
  },
  "sort": {
    "field": "market_value_dollar",
    "direction": "desc"
  },
  "pagination": {
    "page": 1,
    "perPage": 50
  }
}
```

## URL Encoding

The query object must be JSON-stringified and URL-encoded:

```bash theme={null}
curl -X GET "https://api.rwa.xyz/v4/tokens?query=%7B%22filter%22%3A%7B%22operator%22%3A%22equals%22%2C%22field%22%3A%22protocol_slug%22%2C%22value%22%3A%22ondo%22%7D%7D" \
  -H "Authorization: Bearer $RWA_API_KEY"
```

<Note>
  In the API, platforms are referenced as `protocol` in field names (e.g., `protocol_slug`, `protocol_id`) for historical reasons. The terms are interchangeable — "platform" and "protocol" refer to the same entity.
</Note>

## Filtering

Filters allow you to narrow down results based on field values.

### Basic Filter

```json theme={null}
{
  "operator": "equals",
  "field": "protocol_slug",
  "value": "ondo"
}
```

### Composite Filter (AND)

```json theme={null}
{
  "operator": "and",
  "filters": [
    {
      "operator": "equals",
      "field": "network_slug",
      "value": "ethereum"
    },
    {
      "operator": "gte",
      "field": "market_value_dollar",
      "value": 1000000
    }
  ]
}
```

### Composite Filter (OR)

```json theme={null}
{
  "operator": "or",
  "filters": [
    {
      "operator": "equals",
      "field": "protocol_slug",
      "value": "ondo"
    },
    {
      "operator": "equals",
      "field": "protocol_slug",
      "value": "maple"
    }
  ]
}
```

### Supported Operators

**Comparison Operators:**

* `equals` - Exact match
* `notEquals` - Not equal to
* `gt` - Greater than (numbers)
* `gte` - Greater than or equal (numbers)
* `lt` - Less than (numbers)
* `lte` - Less than or equal (numbers)

**String Operators:**

* `like` - Case-sensitive pattern match (use `%` as wildcard)
* `ilike` - Case-insensitive pattern match (use `%` as wildcard)
* `notLike` - Case-sensitive negative match
* `startsWith` - Starts with value
* `endsWith` - Ends with value

**Array Operators:**

* `in` - Value is in array (for array fields)
* `not-in` - Value is not in array
* `includes` - Array includes value (for array fields)
* `not-includes` - Array does not include value

**Date Operators:**

* `before` - Before date
* `onOrBefore` - On or before date
* `after` - After date
* `onOrAfter` - On or after date

**Logical Operators:**

* `and` - All filters must match
* `or` - Any filter must match

### Filter Examples

**Filter by platform:**

```json theme={null}
{
  "operator": "equals",
  "field": "protocol_slug",
  "value": "centrifuge"
}
```

**Filter by minimum market cap:**

```json theme={null}
{
  "operator": "gte",
  "field": "market_value_dollar",
  "value": 5000000
}
```

**Search by name (case-insensitive):**

```json theme={null}
{
  "operator": "ilike",
  "field": "name",
  "value": "%treasury%"
}
```

## Sorting

Sort results by any field in ascending or descending order.

**Sort Structure:**

```json theme={null}
{
  "field": "market_value_dollar",
  "direction": "desc"
}
```

**Directions:**

* `asc` - Ascending order
* `desc` - Descending order
* `""` - No sorting (use default)

**Example:**

```json theme={null}
{
  "sort": {
    "field": "total_asset_value_dollar",
    "direction": "desc"
  }
}
```

## Pagination

Control the number of results returned and navigate through pages.

**Pagination Structure:**

```json theme={null}
{
  "page": 1,
  "perPage": 50
}
```

**Parameters:**

* `page` - Page number (starts at 1)
* `perPage` - Number of results per page (max varies by endpoint, typically 100)

**Example:**

```json theme={null}
{
  "pagination": {
    "page": 2,
    "perPage": 25
  }
}
```

## Aggregation

For aggregate and timeseries endpoints, you can specify aggregation parameters.

**Aggregate Structure:**

```json theme={null}
{
  "groupBy": "protocol_id",
  "aggregateFunction": "sum",
  "interval": "day",
  "mode": "stock"
}
```

**Parameters:**

* `groupBy` - Field to group by (e.g., `network_id`, `asset_class_id`, `date`)
* `aggregateFunction` - Function to apply: `sum`, `avg`, `min`, `max`
* `interval` - Time interval (for timeseries): `day`, `week`, `month`, `year`
* `mode` - Aggregation mode:
  * `stock` - Point-in-time snapshot (latest value per period)
  * `flow` - Aggregate over period (sum/avg/etc. of all values)

**Example:**

```json theme={null}
{
  "aggregate": {
    "groupBy": "date",
    "aggregateFunction": "sum",
    "interval": "month",
    "mode": "stock"
  }
}
```

## Code Examples

### JavaScript/TypeScript

```typescript theme={null}
const API_KEY = process.env.RWA_API_KEY;
const BASE_URL = 'https://api.rwa.xyz';

async function getTopTokens() {
  const query = {
    sort: {
      field: 'market_value_dollar',
      direction: 'desc'
    },
    pagination: {
      page: 1,
      perPage: 10
    }
  };

  const queryParam = encodeURIComponent(JSON.stringify(query));
  const url = `${BASE_URL}/v4/tokens?query=${queryParam}`;

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  const data = await response.json();
  return data;
}
```

### Python

```python theme={null}
import os
import requests
import json
from urllib.parse import quote

API_KEY = os.environ['RWA_API_KEY']
BASE_URL = 'https://api.rwa.xyz'

def get_top_tokens():
    query = {
        'sort': {
            'field': 'market_value_dollar',
            'direction': 'desc'
        },
        'pagination': {
            'page': 1,
            'perPage': 10
        }
    }
    
    query_param = quote(json.dumps(query))
    url = f'{BASE_URL}/v4/tokens?query={query_param}'
    
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    response = requests.get(url, headers=headers)
    return response.json()
```