# NEAR Catalog API

The NEAR Catalog public API returns the projects, categories and tags of the NEAR Protocol ecosystem directory as JSON. It is read-only, needs no API key and is the same data that powers [nearcatalog.xyz](https://nearcatalog.xyz).

This page is the single source of truth for the API. The same Markdown is served raw at [/docs.md](https://nearcatalog.xyz/docs.md), so you can paste it straight into an LLM prompt or fetch it from an agent.

## Overview

| Property | Value |
| --- | --- |
| Base URL | `https://api.nearcatalog.xyz` |
| Protocol | HTTPS, `GET` only |
| Authentication | None. No API key or token is required. |
| Response format | JSON (`Content-Type: application/json; charset=utf-8`) |
| CORS | Responses include `Access-Control-Allow-Origin: *`, so browsers can call the API directly. |

Things to know before you start:

- Project lists are returned as an **object keyed by project slug**, not as an array. Use `Object.values(...)` (JavaScript) or `.values()` (Python) to iterate.
- Pagination is not documented for list endpoints. `/projects` returns every matching project in one response; `/new-projects` accepts a `limit`.
- Errors are not normalised. An unknown `pid` returns HTTP 200 with the JSON value `false`, an unknown `cid` returns an empty `data` object, and an unknown route returns `{"error":"Route not found"}`. Check the response shape instead of relying on the HTTP status alone.
- Tags and categories share one namespace. A category ID such as `dex` is also a tag ID on projects.
- Image URLs in responses point at `https://indexer.nearcatalog.xyz/...`.

## Quick start for AI agents

1. Read the category list once with `GET /categories` to learn valid `cid` values.
2. Find projects with `GET /search?kw=<keyword>` or `GET /projects-by-category?cid=<category-id>`.
3. Load full details for one project with `GET /project?pid=<slug>`. The `slug` field of any list item is the `pid`.
4. Link people to the human-readable site with `https://nearcatalog.xyz/project/<slug>`, or fetch `https://nearcatalog.xyz/project/<slug>.md` for a Markdown summary.

```bash
# Find privacy projects, then read one in full
curl -s "https://api.nearcatalog.xyz/search?kw=privacy"
curl -s "https://api.nearcatalog.xyz/project?pid=nym"
```

Other machine-readable entry points:

- [/llms.txt](https://nearcatalog.xyz/llms.txt) - site summary, categories and a list of projects for LLMs.
- [/llms-full.txt](https://nearcatalog.xyz/llms-full.txt) - the full concatenated knowledge file.
- [/llms-index.txt](https://nearcatalog.xyz/llms-index.txt) - index of every per-project and per-category Markdown page.
- [/docs.md](https://nearcatalog.xyz/docs.md) - this document as raw Markdown.

## The project object

Every endpoint that returns projects uses the same shape. Lists contain a trimmed version; `GET /project` adds the long fields.

| Field | Type | Description |
| --- | --- | --- |
| `slug` | string | Unique project ID. Use it as `pid`. |
| `profile.name` | string | Project name. |
| `profile.tagline` | string | One-line description. |
| `profile.image.url` | string | Logo URL. |
| `profile.tags` | object | Map of tag ID to display name, for example `{"dex": "DEX"}`. |
| `profile.published_date` | integer | Unix timestamp (seconds) when the project was published. |
| `profile.updated_date` | integer | Unix timestamp (seconds) of the last update. |
| `profile.updated_at` | string | Last update as `YYYY-MM-DD HH:mm:ss`. |
| `profile.phase` | string | Project phase: `mainnet`, `testnet`, `prototype`, `still building`, `inactive` or `scam`. |
| `profile.status` | string | Directory status: `active` or `inactive`. Can be an empty string. |
| `profile.lnc` | object or string | Learn NEAR Club info as `{ "score": number, "slug": string }`, or an empty string when none. |

## GET /projects

List all projects. Optionally filter by directory status and project phase. Filters can be combined.

```
GET https://api.nearcatalog.xyz/projects
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | Directory status: `active` or `inactive`. |
| `phase` | string | No | Project phase: `mainnet`, `testnet`, `prototype`, `still building`, `inactive` or `scam`. |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/projects?status=active&phase=mainnet"
```

### Response

`200 OK`. An object keyed by slug. The real response contains one entry per project; only the first is shown here.

```json
{
  "ref-finance": {
    "slug": "ref-finance",
    "profile": {
      "name": "Rhea Finance",
      "tagline": "The Chain-Abstracted Liquidity Solution",
      "image": {
        "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/Rhea-Finance.jpg"
      },
      "tags": {
        "dapp": "Dapp",
        "defi": "DeFi",
        "dex": "DEX"
      },
      "published_date": 1700812920,
      "updated_date": 1790846775,
      "updated_at": "2026-10-01 09:26:15",
      "phase": "mainnet",
      "status": "active",
      "lnc": { "score": 70003, "slug": "reffinance" }
    }
  }
}
```

The `tags` object above is shortened; real projects can carry more tags. Fields are described in [The project object](#the-project-object).

## GET /project

Get the full record of one project, including description, links, token and contract data.

```
GET https://api.nearcatalog.xyz/project?pid={slug}
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `pid` | string | Yes | Project slug, for example `ref-finance`. |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/project?pid=ref-finance"
```

### Response

`200 OK`. A single project object (not wrapped in a slug map). If the project does not exist the body is the JSON value `false`.

```json
{
  "slug": "ref-finance",
  "profile": {
    "name": "Rhea Finance",
    "tagline": "The Chain-Abstracted Liquidity Solution",
    "description": "Rhea is a chain-abstracted liquidity platform on NEAR ...",
    "published_date": 1700812920,
    "updated_date": 1790846775,
    "updated_at": "2026-10-01 09:26:15",
    "image": {
      "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/Rhea-Finance.jpg"
    },
    "tags": { "dapp": "Dapp", "defi": "DeFi", "dex": "DEX" },
    "dapp": "https://app.rhea.finance/points?code=Up5KDhU",
    "linktree": {
      "website": "https://www.rhea.finance/",
      "twitter": "https://x.com/rhea_finance",
      "medium": "https://rhea-finance.medium.com/",
      "telegram": "https://t.me/rhea_finance",
      "discord": "https://discord.com/invite/rheafinance",
      "github": "https://github.com/ref-finance",
      "nearsocial": "",
      "potlock": "",
      "whitepaper": "https://guide.ref.finance/",
      "linkedin": "https://www.linkedin.com/company/ref-finance/",
      "facebook": "",
      "youtube": "",
      "reddit": ""
    },
    "lnc": { "score": 70003, "slug": "reffinance" },
    "phase": "mainnet",
    "status": "active",
    "contracts": { "": "" },
    "tokens": {
      "RHEA": {
        "symbol": "RHEA",
        "name": "RHEA",
        "icon": {
          "thumb": "https://assets.coingecko.com/coins/images/67682/standard/RHEA_Logo.png",
          "small": "https://assets.coingecko.com/coins/images/67682/standard/RHEA_Logo.png"
        },
        "address": { "near": "token.rhealab.near", "aurora": "", "eth": null, "octopus": null },
        "platform": { "coingecko": "rhea-2" }
      }
    }
  }
}
```

The `description` is shortened and the image and icon query strings are removed in this example. In the real response `description` is multi-line plain text, and the object after `tokens` may hold several tokens.

### Response fields

In addition to the fields in [The project object](#the-project-object):

| Field | Type | Description |
| --- | --- | --- |
| `profile.description` | string | Long description. Plain text with newlines; may contain URLs. |
| `profile.dapp` | string | URL of the live app. May be empty. |
| `profile.linktree` | object | External links: `website`, `twitter`, `medium`, `telegram`, `discord`, `github`, `nearsocial`, `potlock`, `whitepaper`, `linkedin`, `facebook`, `youtube`, `reddit`. Missing links are empty strings. Some values (for example `youtube`) can be a channel name rather than a URL. |
| `profile.contracts` | object or array | Associated contracts. Can be a placeholder such as `{ "": "" }` when none are listed. |
| `profile.tokens` | object | Tokens keyed by symbol, with `symbol`, `name`, `icon`, `address` per network and `platform.coingecko`. |

## GET /related-projects

Get projects related to a given project.

```
GET https://api.nearcatalog.xyz/related-projects?pid={slug}
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `pid` | string | Yes | Project slug to find related projects for. |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/related-projects?pid=ref-finance"
```

### Response

`200 OK`. An object keyed by slug, in the list shape described in [The project object](#the-project-object). Only the first of several entries is shown.

```json
{
  "nomo": {
    "slug": "nomo",
    "profile": {
      "name": "NOMO",
      "tagline": "Trading terminal for NEAR markets - discover launches, chart, track positions",
      "image": {
        "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/NOMO.jpg"
      },
      "tags": { "dapp": "Dapp", "dex": "DEX", "launchpad": "Launchpad" },
      "published_date": 1790843234,
      "updated_date": 1791564260,
      "updated_at": "2026-10-09 16:44:20",
      "phase": "mainnet",
      "status": "active",
      "lnc": ""
    }
  }
}
```

## GET /projects-by-category

List projects that belong to a category or tag. Set `cid=trending` to get the trending list.

```
GET https://api.nearcatalog.xyz/projects-by-category?cid={category-id}
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cid` | string | Yes | Category or tag ID, for example `dex`. Use `trending` for trending projects. Valid IDs come from [GET /categories](#get-categories). |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/projects-by-category?cid=dex"
curl -s "https://api.nearcatalog.xyz/projects-by-category?cid=trending"
```

### Response

`200 OK`. Category metadata plus a `data` object keyed by slug. Only the first project is shown.

```json
{
  "cat_title": "DEX",
  "cat_slug": "dex",
  "cat_desc": "",
  "data": {
    "ref-finance": {
      "slug": "ref-finance",
      "profile": {
        "name": "Rhea Finance",
        "tagline": "The Chain-Abstracted Liquidity Solution",
        "image": {
          "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/Rhea-Finance.jpg"
        },
        "tags": { "dapp": "Dapp", "defi": "DeFi", "dex": "DEX" },
        "published_date": 1700812920,
        "updated_date": 1790846775,
        "updated_at": "2026-10-01 09:26:15",
        "phase": "mainnet",
        "status": "active",
        "lnc": { "score": 70003, "slug": "reffinance" }
      }
    }
  }
}
```

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `cat_title` | string or null | Display name of the category. |
| `cat_slug` | string or null | Category ID. |
| `cat_desc` | string or null | Category description. Often empty. |
| `data` | object | Projects keyed by slug, in the list shape described in [The project object](#the-project-object). |

For `cid=trending` the three `cat_*` fields are `null`. An unknown `cid` returns `null` for all three and an empty `data`.

## GET /categories

List every category and tag ID with its display name.

```
GET https://api.nearcatalog.xyz/categories
```

### Query parameters

None.

### Request

```bash
curl -s "https://api.nearcatalog.xyz/categories"
```

### Response

`200 OK`. A flat object mapping category ID to display name. The real response has many more entries (for example `defi`, `nft`, `infrastructure`); four are shown here.

```json
{
  "dapp": "Dapp",
  "infrastructure": "Infrastructure",
  "utilities": "Utilities",
  "other": "Other"
}
```

## GET /search

Search projects by keyword. Matches title, tag ID, category ID and description.

```
GET https://api.nearcatalog.xyz/search?kw={keyword}
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kw` | string | Yes | Search keyword. URL-encode spaces and special characters. Without `kw` the response is an empty array `[]`. |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/search?kw=privacy"
```

### Response

`200 OK`. An object keyed by slug, in the list shape described in [The project object](#the-project-object). Only the first match is shown.

```json
{
  "nym": {
    "slug": "nym",
    "profile": {
      "name": "Nym",
      "tagline": "The next generation of privacy infrastructure.",
      "image": {
        "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/Nym.jpg"
      },
      "tags": { "infrastructure": "Infrastructure", "privacy": "Privacy" },
      "published_date": 1723339234,
      "updated_date": 1791756157,
      "updated_at": "2026-10-11 22:02:37",
      "phase": "mainnet",
      "status": "",
      "lnc": ""
    }
  }
}
```

## GET /new-projects

List the most recently published projects.

```
GET https://api.nearcatalog.xyz/new-projects?limit={n}
```

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Maximum number of projects to return. Without it, 50 projects are returned. |

### Request

```bash
curl -s "https://api.nearcatalog.xyz/new-projects?limit=2"
```

### Response

`200 OK`. An object keyed by slug, in the list shape described in [The project object](#the-project-object). Only the first of the two entries is shown.

```json
{
  "near-mom": {
    "slug": "near-mom",
    "profile": {
      "name": "near.mom",
      "tagline": "Free, independent tools for NEAR builders and power users",
      "image": {
        "url": "https://indexer.nearcatalog.xyz/wp-content/uploads/2026/10/icon.png"
      },
      "tags": { "utilities": "Utilities", "developer-tooling": "Developer Tooling" },
      "published_date": 1792024663,
      "updated_date": 1792024669,
      "updated_at": "2026-10-15 00:37:49",
      "phase": "mainnet",
      "status": "active",
      "lnc": ""
    }
  }
}
```

## Other data sources

These are not part of the API above but are public and useful for agents:

- Awesome NEAR (curated resources) as Markdown: `https://raw.githubusercontent.com/nearcatalog/awesome-near/refs/heads/master/README.md`
- People and contributors on NEAR as JSON: `https://raw.githubusercontent.com/nearcatalog/nearcatalog-people/refs/heads/main/people-on-near.json`