diff --git a/docs/reference/SUMMARY.md b/docs/reference/SUMMARY.md index ffe443726c..c7d2b2a72d 100644 --- a/docs/reference/SUMMARY.md +++ b/docs/reference/SUMMARY.md @@ -70,6 +70,15 @@ spec: sbtc-emily-api ``` +## Hiro-Hosted APIs + +* [API Keys](api/api-keys.md) +* [Rate Limits](api/rate-limits.md) +* [Response Headers](api/response-headers.md) +* Chainhooks API +* Signer Metrics API +* Token Metadata API + ## Clarity * [Functions](clarity/functions.md) diff --git a/docs/reference/api/api-keys.md b/docs/reference/api/api-keys.md new file mode 100644 index 0000000000..8452364ffd --- /dev/null +++ b/docs/reference/api/api-keys.md @@ -0,0 +1,49 @@ +# API Keys + +{% hint style="info" %} +This page documents API key management for Hiro-hosted APIs. Self-hosted Stacks nodes do not require API keys. +{% endhint %} + +{% hint style="info" %} +**Source:** This page is adapted from the [Hiro documentation](https://docs.hiro.so/resources/guides/api-keys). Hiro is a developer tooling company that provides hosted API services for the Stacks ecosystem. +{% endhint %} + +Developers have open access to Hiro's APIs without the use of an API key, but are subject to [Hiro's rate limit policy](rate-limits.md). For developers who need access beyond these rate limits, we provide API keys. + +{% hint style="info" %} +If you're interested in obtaining an API key, you can generate one for free in the [Hiro Platform](https://platform.hiro.so) by creating an account. + +If your app needs more than 500 RPM, please [contact us](mailto:platform@hiro.so). +{% endhint %} + +## Usage with cURL + +The API key is passed in the `header` of your HTTP API request with `x-api-key`. + +```terminal +$ curl https://api.hiro.so/... -H 'x-api-key: ' +``` + +## Usage with Node + +This snippet shows how to perform a `fetch` request with your API key by including it in the request headers. + +```ts +async function makeApiRequest(apiKey: string) { + const url = `https://api.hiro.so/`; + const response = await fetch(url, { + headers: { + "x-api-key": apiKey + } + }); + return response.json(); +} +``` + +{% hint style="warning" %} +**Caution** + +The API key is passed in the header of your HTTP API request and is used only for private use, like in server-side applications. + +If you use the API key in your client-side application, attackers can capture it using the client tools (E.g., browser console) and abuse your API key. +{% endhint %} diff --git a/docs/reference/api/rate-limits.md b/docs/reference/api/rate-limits.md new file mode 100644 index 0000000000..2759d1be63 --- /dev/null +++ b/docs/reference/api/rate-limits.md @@ -0,0 +1,41 @@ +# Rate Limiting + +{% hint style="info" %} +These rate limits apply to Hiro-hosted API endpoints. Self-hosted nodes have no rate limits. +{% endhint %} + +{% hint style="info" %} +**Source:** This page is adapted from the [Hiro documentation](https://docs.hiro.so/resources/guides/rate-limits). Hiro is a developer tooling company that provides hosted API services for the Stacks ecosystem. +{% endhint %} + +## API rate limits + +The following rate-limits (in requests per minute, or RPM) are applicable for [all Hiro APIs](https://www.hiro.so/blog/updated-rate-limits-for-hiro-apis): + +| API key | Rate Limit | +|:--------|:----------------------------------| +| No | 50 requests per minute (RPM) per client IP, for unauthenticated traffic | +| Yes | 500 requests per minute (RPM), regardless of origin IP, with an authenticated API key | + +Rate limits are split between two service types based on the API path: +- **Bitcoin services** (`/ordinals/*` and `/runes/*` paths): Ordinals API and Runes API +- **Stacks services** (all other paths): [Stacks Blockchain API](stacks-blockchain-api/), Token Metadata API, Signer Metrics API, Explorer endpoints, and other Hiro services + +Each service type has its own independent quota, allowing you to use both Stacks and Bitcoin APIs without one affecting the other's rate limits. For more details, see our guide on [response headers](response-headers.md). + +{% hint style="info" %} +Platform services (Platform API, Devnet) have separate rate limiting and are not part of this quota system. +{% endhint %} + +{% hint style="info" %} +You can create an API key for free in the [Hiro Platform](https://platform.hiro.so) by creating an account. +{% endhint %} + +## STX Faucet rate limits + +Note: this faucet is for Stacks testnet and provides testnet STX, which has no monetary value. + +| Type | Rate Limit | +|:-----------------------------|:-----------------------------| +| Stacking requests | 1 request per 2 days | +| Regular STX requests | 1 request per minute (RPM) | diff --git a/docs/reference/api/response-headers.md b/docs/reference/api/response-headers.md new file mode 100644 index 0000000000..8a515816ff --- /dev/null +++ b/docs/reference/api/response-headers.md @@ -0,0 +1,107 @@ +# Response Headers + +{% hint style="info" %} +These response headers apply to Hiro-hosted API endpoints. Self-hosted nodes may return different headers. +{% endhint %} + +{% hint style="info" %} +**Source:** This page is adapted from the [Hiro documentation](https://docs.hiro.so/resources/guides/response-headers). Hiro is a developer tooling company that provides hosted API services for the Stacks ecosystem. +{% endhint %} + +All Hiro APIs return response headers that provide important information about rate limits and usage quotas. These headers are separated by service type (Stacks vs Bitcoin) to provide more granular control over API usage. + +The following headers are returned with every API response: + +```terminal +$ curl -I https://api.hiro.so/extended/v1/info -H 'x-api-key: your-api-key' +``` + +| Header | Description | +|:-------|:------------| +| `ratelimit-limit` | The rate limit ceiling for that endpoint | +| `ratelimit-remaining` | The number of requests left for the current window | +| `ratelimit-reset` | The time when the rate limit window resets (Unix timestamp) | +| `retry-after` | Time to wait before retrying (only present when rate limited) | + +## Service-specific headers + +Hiro APIs include additional headers that provide granular rate limit information per service type, reflecting the separation of rate limits between Stacks and Bitcoin services. + +### Stacks service headers + +When calling Stacks-related endpoints (Stacks Blockchain API, Token Metadata API, etc), you'll receive: + +```typescript +// Example: Fetching Stacks account info +const response = await fetch('https://api.hiro.so/extended/v1/address/SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP/assets', { + headers: { 'x-api-key': apiKey } +}); + +console.log(response) + +// New headers in response: +// x-ratelimit-cost-stacks: 1 +// x-ratelimit-limit-stacks-minute: 500 +// x-ratelimit-remaining-stacks-minute: 499 +``` + +| Header | Description | +|:-------|:------------| +| `x-ratelimit-cost-stacks` | The quota cost for this specific request | +| `x-ratelimit-limit-stacks-second` | Per-second limit for Stacks services | +| `x-ratelimit-remaining-stacks-second` | Remaining requests this second | +| `x-ratelimit-limit-stacks-minute` | Per-minute limit for Stacks services | +| `x-ratelimit-remaining-stacks-minute` | Remaining requests this minute | +| `x-ratelimit-limit-stacks-month` | Monthly limit for Stacks services | +| `x-ratelimit-remaining-stacks-month` | Remaining requests this month | + +### Bitcoin service headers + +{% hint style="info" %} +Bitcoin service headers (`x-ratelimit-*-bitcoin`) apply to the Ordinals and Runes APIs hosted by Hiro. For full documentation on these APIs, see the [Hiro documentation](https://docs.hiro.so/apis/ordinals-api). +{% endhint %} + +When calling Bitcoin-related endpoints (Ordinals API, Runes API), you'll receive: + +```typescript +// Example: Fetching inscription data +const response = await fetch('https://api.hiro.so/ordinals/v1/inscriptions', { + headers: { 'x-api-key': apiKey } +}); + +console.log(response) + +// New headers in response: +// x-ratelimit-cost-bitcoin: 1 +// x-ratelimit-limit-bitcoin-minute: 500 +// x-ratelimit-remaining-bitcoin-minute: 499 +``` + +| Header | Description | +|:-------|:------------| +| `x-ratelimit-cost-bitcoin` | The quota cost for this specific request | +| `x-ratelimit-limit-bitcoin-second` | Per-second limit for Bitcoin services | +| `x-ratelimit-remaining-bitcoin-second` | Remaining requests this second | +| `x-ratelimit-limit-bitcoin-minute` | Per-minute limit for Bitcoin services | +| `x-ratelimit-remaining-bitcoin-minute` | Remaining requests this minute | +| `x-ratelimit-limit-bitcoin-month` | Monthly limit for Bitcoin services | +| `x-ratelimit-remaining-bitcoin-month` | Remaining requests this month | + +## Service classification + +APIs are classified into service types based on their URL path: + +| Service Type | Path Pattern | Examples | +|:-------------|:-------------|:---------| +| Bitcoin | `/ordinals/*` | Ordinals API endpoints | +| Bitcoin | `/runes/*` | Runes API endpoints | +| Stacks | All other paths | Stacks Blockchain API, Token Metadata API, Signer Metrics API, Explorer, and other services | + +{% hint style="info" %} +The `x-ratelimit-cost-*` header shows the exact quota cost for each request, which may vary based on the endpoint and parameters used. Platform services (Platform API, Devnet) have separate rate limiting. +{% endhint %} + +## Further reading + +- [Rate limiting](rate-limits.md) +- [API keys](api-keys.md) diff --git a/docs/reference/api/stacks-node-rpc/README.md b/docs/reference/api/stacks-node-rpc/README.md index e20516d3a7..b2cde47bc9 100644 --- a/docs/reference/api/stacks-node-rpc/README.md +++ b/docs/reference/api/stacks-node-rpc/README.md @@ -22,6 +22,10 @@ If you run a local Stacks node, it exposes an HTTP server on port `20443`. The i Looking for the indexed Stacks Blockchain API? See the [Stacks Blockchain API reference](../stacks-blockchain-api/). {% endhint %} +{% hint style="info" %} +This is the **self-hosted RPC endpoint** exposed by every Stacks node. It does not require [API keys](../api-keys.md) and is not subject to Hiro's [rate limits](../rate-limits.md). The Hiro-hosted Stacks Blockchain API, by contrast, is a managed service that proxies and extends these RPC endpoints with additional indexing, caching, and query capabilities. +{% endhint %} + Note that the [Stacks Node RPC API](https://github.com/stacks-network/stacks-blockchain/) and the [Hiro Stacks Blockchain API](https://www.hiro.so/stacks-api) are two different things. The Hiro API is a centralized service run by Hiro, a developer tooling company, that makes it easy to get onboarded and begin interacting with the Stacks blockchain in a RESTful way. The Hiro API is a proxy for the Stacks Node RPC API that makes it a bit easier to work with by providing additional functionality. The Stacks Node RPC API is generated by every Stacks node and allows developers to self-host their own node and API for a more decentralized architecture.