Requests

Every /v4/* endpoint supports two ways to filter, sort, and paginate results: simple flattened query parameters for common cases, and a JSON-based query parameter for more complex filtering, sorting, and aggregation. Every endpoint has a corresponding /meta endpoint that returns the available fields, allowed operators, and valid values.

Basic Example: Flattened Query Parameters

For common cases, pass filtering, sorting, and pagination directly as URL parameters:

GET https://api.rwa.xyz/v4/assets?ticker=USDC
GET https://api.rwa.xyz/v4/assets?page=1&per_page=50
GET https://api.rwa.xyz/v4/assets?sort=name&sort_direction=asc

These flattened parameters are supported on every /v4/* endpoint:

search - Free-text search across common fields (e.g., name, ticker)
<field> - Filter directly by any field name (e.g., ticker=USDC)
page - Page number (starts at 1)
per_page - Number of results per page
sort - Field to sort by
sort_direction - asc or desc

curl -G 'https://api.rwa.xyz/v4/assets' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'search=USDC'

Advanced Example: JSON Query Object

For more complex filtering — composite and/or conditions, aggregation, or anything the flattened parameters can’t express — pass a JSON-based query language 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)

{
  "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:

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"

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.

Filtering

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

Basic Filter

{
  "operator": "equals",
  "field": "protocol_slug",
  "value": "ondo"
}

Composite Filter (AND)

{
  "operator": "and",
  "filters": [
    {
      "operator": "equals",
      "field": "network_slug",
      "value": "ethereum"
    },
    {
      "operator": "gte",
      "field": "market_value_dollar",
      "value": 1000000
    }
  ]
}

Composite Filter (OR)

{
  "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

Null Operators:

is_null - Field value is null
is_not_null - Field value is not null

Logical Operators:

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

Filter Examples

Filter by platform:

{
  "operator": "equals",
  "field": "protocol_slug",
  "value": "centrifuge"
}

Filter by minimum market cap:

{
  "operator": "gte",
  "field": "market_value_dollar",
  "value": 5000000
}

Search by name (case-insensitive):

{
  "operator": "ilike",
  "field": "name",
  "value": "%treasury%"
}

Sorting

Sort results by any field in ascending or descending order. Sort Structure:

{
  "field": "market_value_dollar",
  "direction": "desc"
}

Directions:

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

Example:

{
  "sort": {
    "field": "total_asset_value_dollar",
    "direction": "desc"
  }
}

Pagination

Control the number of results returned and navigate through pages. Pagination Structure:

{
  "page": 1,
  "perPage": 50
}

Parameters:

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

Example:

{
  "pagination": {
    "page": 2,
    "perPage": 25
  }
}

Aggregation

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

{
  "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:

{
  "aggregate": {
    "groupBy": "date",
    "aggregateFunction": "sum",
    "interval": "month",
    "mode": "stock"
  }
}

Code Examples

JavaScript/TypeScript

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

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()

Home

Methodology

Frameworks

Data Schemas

MCP Server

API

Basic Example: Flattened Query Parameters

Advanced Example: JSON Query Object

URL Encoding

Filtering

Basic Filter

Composite Filter (AND)

Composite Filter (OR)

Supported Operators

Filter Examples

Sorting

Aggregation

Code Examples

JavaScript/TypeScript

Python

​Basic Example: Flattened Query Parameters

​Advanced Example: JSON Query Object

​URL Encoding

​Filtering

​Basic Filter

​Composite Filter (AND)

​Composite Filter (OR)

​Supported Operators

​Filter Examples

​Sorting

​Pagination

​Aggregation

​Code Examples

​JavaScript/TypeScript

​Python

Basic Example: Flattened Query Parameters

Advanced Example: JSON Query Object

URL Encoding

Filtering

Basic Filter

Composite Filter (AND)

Composite Filter (OR)

Supported Operators

Filter Examples

Sorting

Pagination

Aggregation

Code Examples

JavaScript/TypeScript

Python