> ## 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.

# Examples

> Make your first API calls in minutes

This guide walks you through a series of API calls that demonstrate every major endpoint and query pattern — filtering, sorting, pagination, timeseries, and aggregation.

## Prerequisites

1. [Obtain an API key](/api/overview#obtaining-an-api-key)
2. Set it as an environment variable:

```bash theme={null}
export RWA_API_KEY="your_api_key_here"
```

## Find U.S. Treasury assets

Fetch all assets in the U.S. Treasuries asset class, sorted by market value.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/assets' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "equals",
      "field": "asset_class_name",
      "value": "US Treasury Debt"
    },
    "sort": {
      "field": "circulating_market_value_dollar",
      "direction": "desc"
    },
    "pagination": {
      "page": 1,
      "perPage": 5
    }
  }'
```

* `filter` narrows results to assets classified as `US Treasury Debt`
* `sort` orders by market value, largest first
* `pagination` limits to 5 results on page 1

**Response:**

```json theme={null}
{
  "results": [
    {
      "id": 51,
      "name": "Circle USYC",
      "slug": "circle-usyc",
      "ticker": "USYC",
      "asset_class_name": "US Treasury Debt",
      "issuer_name": "Circle International",
      "circulating_market_value_dollar": {
        "val": 2394947347.33,
        "val_7d": 2118658299.28,
        "chg_7d_pct": 13.04
      },
      "yield_to_maturity_percent": {
        "val": 0.0383,
        "val_7d": 0.0383
      }
      // ... ~200 fields total per asset
    }
  ],
  "pagination": { "page": 1, "perPage": 5, "pageCount": 17, "resultCount": 83 }
}
```

Numeric metrics are returned as objects with the current value (`val`) plus historical snapshots (`val_7d`, `val_30d`, `val_90d`) and deltas (`chg_7d_amt`, `chg_7d_pct`, etc.).

Note the `id` field — you'll use it in later examples.

## Browse asset managers

The `/v4/managers` endpoint lists entities that manage RWA funds. This is one of several entity endpoints (`/v4/issuers`, `/v4/platforms`, `/v4/networks`) that all support the same query language.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/managers' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "sort": {
      "field": "asset_count",
      "direction": "desc"
    },
    "pagination": {
      "page": 1,
      "perPage": 5
    }
  }'
```

**Response:**

```json theme={null}
{
  "results": [
    {
      "id": 74,
      "name": "Reental America",
      "slug": "reental-america",
      "asset_count": 20,
      "website": "https://www.reental.co/en",
      "holding_addresses_count": { "val": 5699, "val_7d": 5707, "chg_7d_pct": -0.14 },
      "bridged_token_value_dollar": { "val": 29034335.51, "val_7d": 29050231.26 }
      // ...
    }
  ],
  "pagination": { "page": 1, "perPage": 5, "pageCount": 22, "resultCount": 106 }
}
```

## List an asset's tokens

An **asset** represents a financial product (e.g., "Ondo Short-Term US Government Bond Fund"). A **token** is a specific on-chain deployment of that asset — the same asset can have tokens on multiple chains.

Use `/v4/tokens` to see all the on-chain tokens for a given asset.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/tokens' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "equals",
      "field": "asset_id",
      "value": "51"
    }
  }'
```

**Response:**

```json theme={null}
{
  "results": [
    {
      "id": 20,
      "name": "Ethereum USYC",
      "asset_id": 51,
      "network_name": "Ethereum",
      "address": "0x136471a34f6ef19fe...",
      "decimals": 6,
      "standards": ["ERC-20"],
      "protocol_name": "Circle",
      "transferability_type": "Transferable within whitelist",
      "total_supply_token": { "val": 113140795.54, "val_7d": 109385452.12 }
      // ...
    },
    {
      "id": 4801,
      "name": "BNB Chain USYC",
      "asset_id": 51,
      "network_name": "BNB Chain",
      "address": "0x8d0fa28f221eb5735b..."
      // ...
    },
    {
      "id": 5076,
      "name": "Solana USYC",
      "asset_id": 51,
      "network_name": "Solana",
      "address": "7LWanZteUKtvFjv4MHYg..."
      // ...
    }
  ]
}
```

This shows the same asset (Circle USYC) deployed as three separate tokens on Ethereum, BNB Chain, and Solana. Each token has its own supply, address, and on-chain metrics.

## Get historical NAV for an asset

Use `/v4/assets/aggregates/timeseries` to pull historical metrics for an asset. The timeseries endpoints require a `measure_slug` filter to specify which metric you want — use the [Data Catalog](https://app.rwa.xyz/catalog) or the [`/v4/assets/aggregates/meta`](/api/meta) endpoint to discover available measures.

Replace `ASSET_ID` with an `id` from a previous response.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/assets/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        {
          "operator": "equals",
          "field": "asset_id",
          "value": "ASSET_ID"
        },
        {
          "operator": "equals",
          "field": "measure_slug",
          "value": "net_asset_value_dollar"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "perPage": 30
    }
  }'
```

* `filter` combines two conditions with `and` — a specific asset and the NAV measure
* The timeseries endpoint defaults to daily granularity when no `aggregate` block is provided

**Response:**

Each result contains a `measure` descriptor, a `group` descriptor, and an array of `points` where each point is a `[date, value]` pair.

```json theme={null}
{
  "results": [
    {
      "measure": {
        "id": 3,
        "slug": "net_asset_value_dollar",
        "name": "Net Asset Value (Dollar)",
        "unit": "dollar"
      },
      "group": {
        "id": 51,
        "type": "asset",
        "name": "Circle USYC",
        "color": "#2A3758"
      },
      "points": [
        ["2023-10-19", 1.01577],
        ["2023-10-20", 1.01590]
      ]
    }
  ],
  "pagination": { "page": 1, "perPage": 30, "pageCount": 1, "resultCount": 1 }
}
```

## Track token supply across chains

Use `/v4/tokens/aggregates/timeseries` instead of the asset timeseries when you need chain-level granularity. The `aggregate.groupBy: "token"` option returns a separate series for each on-chain token, so you can see how supply is distributed across networks.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/tokens/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        {
          "operator": "equals",
          "field": "asset_id",
          "value": "51"
        },
        {
          "operator": "equals",
          "field": "measure_slug",
          "value": "total_supply_token"
        }
      ]
    },
    "aggregate": {
      "groupBy": "token",
      "aggregateFunction": "sum",
      "interval": "day",
      "mode": "stock"
    }
  }'
```

* `groupBy: "token"` returns one series per on-chain token (e.g., Ethereum USYC, Solana USYC)
* `mode: "stock"` returns point-in-time snapshots (use `"flow"` to accumulate values over a period)
* Compare with the previous example: asset timeseries gives you one combined series, token timeseries breaks it out per chain

**Response:**

```json theme={null}
{
  "results": [
    {
      "measure": { "slug": "total_supply_token", "name": "Total Supply (Token)", "unit": "token" },
      "group": { "type": "token", "name": "Ethereum USYC" },
      "points": [
        ["2023-06-13", 25000],
        ["2023-06-14", 25000]
      ]
    },
    {
      "measure": { "slug": "total_supply_token", "name": "Total Supply (Token)", "unit": "token" },
      "group": { "type": "token", "name": "BNB Chain USYC" },
      "points": [
        ["2025-07-09", 1.83],
        ["2025-07-10", 1.83]
      ]
    }
  ]
}
```

## Aggregate value across an asset class

To see the total value for **all** assets in a class combined, use `aggregate.groupBy: "asset_class"`. This sums across every asset in the category.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/assets/aggregates/timeseries' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        {
          "operator": "equals",
          "field": "asset_class_name",
          "value": "US Treasury Debt"
        },
        {
          "operator": "equals",
          "field": "measure_slug",
          "value": "net_asset_value_dollar"
        }
      ]
    },
    "aggregate": {
      "groupBy": "asset_class",
      "aggregateFunction": "sum",
      "interval": "month",
      "mode": "stock"
    }
  }'
```

* `groupBy: "asset_class"` sums values across all assets in the class into a single series
* `interval: "month"` returns one data point per month
* This gives you the total market size of tokenized U.S. Treasuries over time

**Response:**

```json theme={null}
{
  "results": [
    {
      "measure": { "slug": "net_asset_value_dollar", "name": "Net Asset Value (Dollar)", "unit": "dollar" },
      "group": { "id": 27, "type": "asset_class", "name": "US Treasury Debt", "color": "#05417a" },
      "points": [
        ["2021-04-01", 25],
        ["2021-05-01", 31],
        ["2025-01-01", 3500000000],
        ["2025-02-01", 3800000000]
      ]
    }
  ]
}
```

## Query on-chain transactions

Use `/v4/transactions` to query individual on-chain events — mints, burns, and transfers. This example finds large transactions (over \$100,000 USD) for a specific asset, demonstrating comparison operators like `gte`.

```bash theme={null}
curl -G 'https://api.rwa.xyz/v4/transactions' \
  -H "Authorization: Bearer $RWA_API_KEY" \
  --data-urlencode 'query={
    "filter": {
      "operator": "and",
      "filters": [
        {
          "operator": "equals",
          "field": "asset_id",
          "value": 51
        },
        {
          "operator": "gte",
          "field": "usd_amount",
          "value": 100000
        }
      ]
    },
    "sort": { "field": "date", "direction": "desc" },
    "pagination": { "page": 1, "perPage": 5 }
  }'
```

* `gte` (greater than or equal) is one of several comparison operators — see [Requests](/api/requests) for the full list
* Transactions default to `date` descending, but we include it explicitly for clarity
* Each result includes nested `asset`, `token`, and `transaction_type` objects

**Response:**

```json theme={null}
{
  "results": [
    {
      "id": "1-0x9d60a645b0a92c98...-42",
      "date": "2026-03-17T00:00:00.000Z",
      "timestamp": "2026-03-17T11:02:59.000Z",
      "transaction_hash": "0x9d60a645b0a92c98...",
      "amount": 22331806.95,
      "usd_amount": 24995829.91,
      "from_address": "0xfd78ee919681417d...",
      "to_address": "0x0000000000000000...",
      "transaction_type": {
        "id": 2,
        "slug": "token-burn",
        "name": "Token Burn",
        "description": "Tokens are destroyed and removed from the circulating supply."
      },
      "token": { "id": "20", "asset_id": "51", "network_name": "Ethereum", "address": "0x136471a34f..." },
      "asset": { "id": "51", "name": "Circle USYC", "asset_class_name": "US Treasury Debt" }
    }
  ],
  "pagination": { "page": 1, "perPage": 5, "pageCount": 6216, "resultCount": 31078 }
}
```

<Note>
  The transactions endpoint is rate limited to 120 requests per hour per organization. See [Rate Limits](/api/overview#rate-limits).
</Note>

## Discovering available fields

Every resource endpoint has a corresponding [`/meta` endpoint](/api/meta) that returns the available fields, their types, valid filter operators, and select options. This is useful for building dynamic queries or exploring what's filterable.

```bash theme={null}
curl -X GET 'https://api.rwa.xyz/v4/assets/meta' \
  -H "Authorization: Bearer $RWA_API_KEY"
```

## Next steps

* **[Requests](/api/requests)** — full reference for filters, sorting, pagination, and aggregation
* **[Endpoints](/api/endpoints)** — overview of all available endpoints
* **[Assets schema](/schemas/assets)** — complete field reference for assets
* **[Tokens schema](/schemas/tokens)** — complete field reference for tokens
* **[Data Catalog](https://app.rwa.xyz/catalog)** — browse all entities, fields, and measures