> For the complete documentation index, see [llms.txt](https://hashly.gitbook.io/hashly-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hashly.gitbook.io/hashly-docs/technical/public-api.md).

# Public API

The **Hashly Public API** gives read-only access to Hashly's Hedera data: events, tokens, NFT collections, ecosystem projects and the season leaderboard. It speaks JSON over HTTPS, and the interactive reference is at [hash-ly.com/api-docs](https://hash-ly.com/api-docs).

***

## 🌐 Basics

|                      |                                                                            |
| -------------------- | -------------------------------------------------------------------------- |
| **Base URL**         | `https://hash-ly.com/api/v1`                                               |
| **Methods**          | `GET` only                                                                 |
| **Format**           | JSON                                                                       |
| **Authentication**   | API key                                                                    |
| **Reference**        | [hash-ly.com/api-docs](https://hash-ly.com/api-docs)                       |
| **OpenAPI document** | [hash-ly.com/api/v1/openapi.json](https://hash-ly.com/api/v1/openapi.json) |

The API directory at [hash-ly.com/api/v1](https://hash-ly.com/api/v1) and the OpenAPI document are open to everyone. Every data endpoint needs a key.

***

## 🔑 Authentication

Send your key in the `Authorization` header:

```bash
curl -H "Authorization: Bearer hk_live_..." \
  "https://hash-ly.com/api/v1/events?limit=5"
```

You can also pass it as a query parameter, `?api_key=<key>`, but the header keeps it out of URLs and logs.

### 🎟️ Getting a Key

Keys are issued by hand, one per person or project, so Hashly can see who is calling and turn one off without affecting anyone else. Ask on X at [@hashly\_h](https://x.com/hashly_h) or by email at <contact@hash-ly.com>.

* 🔤 A key starts with `hk_live_`.
* 🔒 It's shown once. Hashly stores only a hash of it, so a lost key can't be recovered and a new one is issued.
* 🚫 A revoked key stops working straight away.

***

## 📋 Endpoints

| Endpoint               | What it returns                                                                              | Parameters                                         |
| ---------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `GET /events`          | Approved events, soonest first                                                               | `status`, `eventType`, `source`, `limit`, `offset` |
| `GET /events/{id}`     | One approved event, with its links and prizes                                                | —                                                  |
| `GET /tokens/top`      | Approved tokens ordered by their stored vote total (`totalVotes`), with price and market cap | `limit`                                            |
| `GET /collections/top` | Approved NFT collections ordered by `totalVotes`, with owners and supply                     | `limit`                                            |
| `GET /leaderboard`     | The current season's leaderboard and the season's dates                                      | `limit`                                            |
| `GET /ecosystem`       | Approved ecosystem projects, newest first                                                    | `category`, `country`, `limit`, `offset`           |

### ⚙️ Parameters

| Parameter              | Values                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `status` (events)      | `upcoming`, `live`, `ended` or `all`. Without it, ended events are left out                                                        |
| `eventType` (events)   | `MINT_EVENT`, `ECOSYSTEM_MEETUP`, `HACKATHON` or `OTHER`                                                                           |
| `source` (events)      | `SENTX` or `KABILA`                                                                                                                |
| `category` (ecosystem) | `DEFI`, `TOOLS`, `MARKETPLACE`, `DATA`, `COMMUNITY`, `WALLET`, `BRIDGE`, `GAMING`, `NFT`, `EDUCATION`, `INFRASTRUCTURE` or `OTHER` |
| `country` (ecosystem)  | Two-letter country code, such as `ES`                                                                                              |
| `limit`                | 1 to 100. Defaults: 20 for events, 30 for tokens and collections, 50 for the leaderboard and ecosystem                             |
| `offset`               | Where to start, for paging events and ecosystem projects                                                                           |

List responses for events and ecosystem projects include `total` and `hasMore` for paging.

***

## ⏱️ Limits

* 🚦 **100 requests per minute** from the same IP address. Past that you get a `429` with a `Retry-After` header saying how many seconds to wait.
* 📖 **Read-only.** Any method other than `GET` is refused with a `405`.
* 📄 **At most 100 items** per request.

***

## ❗ Errors

Key and lookup errors come back as JSON with an `error` message and a stable `code` you can branch on:

| Status | Code              | Meaning                              |
| ------ | ----------------- | ------------------------------------ |
| `401`  | `MISSING_API_KEY` | No key on the request                |
| `401`  | `INVALID_API_KEY` | Not a key Hashly issued              |
| `401`  | `REVOKED_API_KEY` | The key has been revoked             |
| `404`  | `NOT_FOUND`       | No approved event with that ID       |
| `405`  | —                 | The API only accepts `GET`           |
| `429`  | —                 | Too many requests; see `Retry-After` |

***

## 📜 Terms of Use

Using the API means accepting Hashly's [Terms of Use](https://hash-ly.com/terms). Stay within the limits of your key, and don't use the API to overload Hashly. Data from the API is information, not financial advice, and much of it comes from third parties and the community.

***

## 💡 Tips

* 🧭 **Start with the directory** at `/api/v1`: it lists every endpoint and its parameters without a key.
* 🧪 **Try requests in the browser** from [hash-ly.com/api-docs](https://hash-ly.com/api-docs).
* 📄 **Page with `limit` and `offset`** and stop when `hasMore` is `false`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hashly.gitbook.io/hashly-docs/technical/public-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.