From 1975acd149aeebef1b0abeadd7b6b2a6122ea706 Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Tue, 24 Mar 2026 14:58:50 -0700 Subject: [PATCH 1/2] Add shared Hiro API infrastructure pages (keys, rate limits, headers) Faithfully migrates API keys, rate limits, and response headers documentation from Hiro docs. Includes actual rate limit numbers, security warnings, and service classification details that were missing from the original migration attempt. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/reference/SUMMARY.md | 9 ++ docs/reference/api/api-keys.md | 49 +++++++++ docs/reference/api/rate-limits.md | 41 +++++++ docs/reference/api/response-headers.md | 107 +++++++++++++++++++ docs/reference/api/stacks-node-rpc/README.md | 4 + 5 files changed, 210 insertions(+) create mode 100644 docs/reference/api/api-keys.md create mode 100644 docs/reference/api/rate-limits.md create mode 100644 docs/reference/api/response-headers.md 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. From 09ae226e82e407b748d682fea72ba41daedd2c89 Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Tue, 24 Mar 2026 15:02:57 -0700 Subject: [PATCH 2/2] Add Chainhooks, Signer Metrics, and Token Metadata API reference sections Faithfully migrates 3 Hiro API reference sections with complete content preservation. Each section includes overview, usage guide, and prominent links to the full OpenAPI-powered interactive reference on Hiro docs. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../create-a-token/fungible-tokens.md | 2 +- .../create-a-token/non-fungible-tokens.md | 2 +- .../run-a-signer/how-to-monitor-signer.md | 4 + docs/reference/SUMMARY.md | 6 + docs/reference/api/chainhooks-api/README.md | 59 ++++ docs/reference/api/chainhooks-api/usage.md | 288 ++++++++++++++++++ .../api/signer-metrics-api/README.md | 46 +++ .../reference/api/signer-metrics-api/usage.md | 50 +++ .../api/token-metadata-api/README.md | 50 +++ .../reference/api/token-metadata-api/usage.md | 50 +++ 10 files changed, 555 insertions(+), 2 deletions(-) create mode 100644 docs/reference/api/chainhooks-api/README.md create mode 100644 docs/reference/api/chainhooks-api/usage.md create mode 100644 docs/reference/api/signer-metrics-api/README.md create mode 100644 docs/reference/api/signer-metrics-api/usage.md create mode 100644 docs/reference/api/token-metadata-api/README.md create mode 100644 docs/reference/api/token-metadata-api/usage.md diff --git a/docs/build/get-started/create-a-token/fungible-tokens.md b/docs/build/get-started/create-a-token/fungible-tokens.md index afdb165c46..e51f737c50 100644 --- a/docs/build/get-started/create-a-token/fungible-tokens.md +++ b/docs/build/get-started/create-a-token/fungible-tokens.md @@ -240,7 +240,7 @@ If you plan on updating your token's metadata in the future, you should definite ;; ... ``` -Hiro’s [Token Metadata API](https://www.hiro.so/token-metadata-api) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing token’s metadata. +Hiro’s [Token Metadata API](../../../reference/api/token-metadata-api/) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing token’s metadata. If your token contract did not implement this print event, you could use the helper contract below to invoke a function that'll emit the same print event notification. Just invoke the `ft-metadata-update-notify` function of this contract below: diff --git a/docs/build/get-started/create-a-token/non-fungible-tokens.md b/docs/build/get-started/create-a-token/non-fungible-tokens.md index ef064e622e..9e5b8d37fd 100644 --- a/docs/build/get-started/create-a-token/non-fungible-tokens.md +++ b/docs/build/get-started/create-a-token/non-fungible-tokens.md @@ -186,7 +186,7 @@ If you plan on updating your NFT's metadata in the future, you should definitely ;; ... -Hiro’s [Token Metadata API](https://www.hiro.so/token-metadata-api) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing NFT’s metadata. +Hiro’s [Token Metadata API](../../../reference/api/token-metadata-api/) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing NFT’s metadata. If your NFT contract did not implement this print event, you could use the helper contract below to invoke a function that'll emit the same print event notification. Just invoke the `nft-metadata-update-notify` function of this contract below: diff --git a/docs/operate/run-a-signer/how-to-monitor-signer.md b/docs/operate/run-a-signer/how-to-monitor-signer.md index 8bfee6061b..5c402f84ec 100644 --- a/docs/operate/run-a-signer/how-to-monitor-signer.md +++ b/docs/operate/run-a-signer/how-to-monitor-signer.md @@ -1,5 +1,9 @@ # How to Monitor Signer +{% hint style="info" %} +For programmatic monitoring of signer behavior, block acceptance rates, and PoX cycle metrics via REST API, see the [Signer Metrics API reference](../../reference/api/signer-metrics-api/). +{% endhint %} + We will use [Grafana Cloud](https://grafana.com/) to observe and monitor both the Signer and its corresponding Stacks node. ## Requirements diff --git a/docs/reference/SUMMARY.md b/docs/reference/SUMMARY.md index c7d2b2a72d..c61642724f 100644 --- a/docs/reference/SUMMARY.md +++ b/docs/reference/SUMMARY.md @@ -69,6 +69,12 @@ kind: openapi spec: sbtc-emily-api ``` +* [Chainhooks API](api/chainhooks-api/README.md) + * [Usage](api/chainhooks-api/usage.md) +* [Signer Metrics API](api/signer-metrics-api/README.md) + * [Usage](api/signer-metrics-api/usage.md) +* [Token Metadata API](api/token-metadata-api/README.md) + * [Usage](api/token-metadata-api/usage.md) ## Hiro-Hosted APIs diff --git a/docs/reference/api/chainhooks-api/README.md b/docs/reference/api/chainhooks-api/README.md new file mode 100644 index 0000000000..cad2e01d42 --- /dev/null +++ b/docs/reference/api/chainhooks-api/README.md @@ -0,0 +1,59 @@ +# Chainhooks API + +REST API for managing Chainhooks programmatically. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/chainhooks-api). +{% endhint %} + +## Overview + +The Chainhooks API is a REST API that allows you to programmatically manage chainhooks, configure event filters, and control webhook delivery. It provides the same functionality covered in the [Chainhooks SDK introduction](https://docs.hiro.so/en/tools/chainhooks/introduction) through direct HTTP requests. + +## Key Features + +- **Full chainhook management** - Create, read, update, and delete chainhooks +- **Webhook configuration** - Set up HTTP POST endpoints for event delivery +- **Evaluation endpoints** - Test chainhooks against historical blocks + +## Base URLs + +The Chainhooks API is available on both mainnet and testnet: + +``` +Testnet: https://api.testnet.hiro.so/chainhooks/v1 +Mainnet: https://api.mainnet.hiro.so/chainhooks/v1 +``` + +## API Reference + +{% hint style="info" %} +For the complete interactive API reference with all endpoints, request/response schemas, and try-it-out functionality, see the [Chainhooks API Reference on Hiro Docs](https://docs.hiro.so/en/apis/chainhooks-api/reference/chainhooks). +{% endhint %} + +### Available Endpoints + +| Endpoint | Description | +|----------|-------------| +| Register chainhook | Create a new chainhook with event filters and webhook delivery | +| Get all chainhooks | List all registered chainhooks | +| Get one chainhook | Retrieve a specific chainhook by UUID | +| Update chainhook | Modify an existing chainhook configuration | +| Delete chainhook | Remove a registered chainhook | +| Evaluate chainhook | Test a chainhook against historical blocks | +| Enable chainhook | Enable a specific chainhook | +| Disable chainhook | Disable a specific chainhook | +| Bulk enable/disable | Enable or disable multiple chainhooks matching filters | +| Get status | Retrieve the current status of a chainhook | +| Rotate secret | Rotate the consumer secret for webhook security | +| Delete secret | Remove the consumer secret | + +## Next Steps + +- [Usage Guide](usage.md): Authentication and best practices +- [API Reference](https://docs.hiro.so/en/apis/chainhooks-api/reference/chainhooks): Complete endpoint documentation + +{% hint style="info" %} +### Need help building with the Chainhooks API? +Reach out to us on the **#chainhook** channel on [Discord](https://stacks.chat/) under Hiro Developer Tools. There's also a [weekly office hours](https://www.addevent.com/event/oL21905919) call every Thursday at 11am ET. +{% endhint %} diff --git a/docs/reference/api/chainhooks-api/usage.md b/docs/reference/api/chainhooks-api/usage.md new file mode 100644 index 0000000000..aa31b4d597 --- /dev/null +++ b/docs/reference/api/chainhooks-api/usage.md @@ -0,0 +1,288 @@ +# Usage + +Learn how to authenticate, make requests, and handle responses with the Chainhooks API. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/chainhooks-api/usage). +{% endhint %} + +## Authentication + +All Chainhooks API requests require authentication using a Hiro API key. + +### Get Your API Key + +1. Visit [platform.hiro.so](https://platform.hiro.so) +2. Sign in or create an account +3. Navigate to API Keys +4. Generate or copy your API key + +### Using Your API Key + +Include your API key in the `x-api-key` header for all requests: + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" +``` + +**Security best practices:** +- Store API keys in environment variables, never in code +- Use different keys for development and production +- Rotate keys periodically +- Never commit keys to version control + +## Base URLs + +Use the appropriate base URL for your environment: + +``` +Testnet: https://api.testnet.hiro.so/chainhooks/v1 +Mainnet: https://api.mainnet.hiro.so/chainhooks/v1 +``` + +**Always test on testnet first** before deploying to mainnet. + +## Request Format + +### Headers + +All requests should include: + +```http +Content-Type: application/json +x-api-key: YOUR_API_KEY +``` + +### Request Body + +Most endpoints accept JSON request bodies. Example for registering a chainhook: + +```bash +curl -X POST https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-chainhook", + "version": "1", + "chain": "stacks", + "network": "testnet", + "filters": { + "events": [{ + "type": "stx_transfer", + "sender": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" + }] + }, + "action": { + "type": "http_post", + "url": "https://example.com/webhooks" + } + }' +``` + +## Response Format + +### Success Responses + +Successful responses return JSON with relevant data: + +```json +{ + "uuid": "123e4567-e89b-12d3-a456-426614174000", + "definition": { + "name": "my-chainhook", + "version": "1", + "chain": "stacks", + "network": "testnet", + ... + }, + "status": { + "status": "new", + "enabled": false, + "created_at": 1234567890, + ... + } +} +``` + +### HTTP Status Codes + +| Code | Meaning | Description | +|------|---------|-------------| +| 200 | OK | Request succeeded, response body contains data | +| 204 | No Content | Request succeeded, no response body | +| 400 | Bad Request | Invalid request format or parameters | +| 401 | Unauthorized | Missing or invalid API key | +| 404 | Not Found | Chainhook UUID not found | +| 429 | Too Many Requests | Rate limit exceeded | +| 500 | Server Error | Internal server error | + +### Error Responses + +Error responses include details about what went wrong: + +```json +{ + "error": "Invalid request body", + "details": "filters.events is required" +} +``` + +## Common Patterns + +### List All Chainhooks + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" +``` + +### Get a chainhook + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/{uuid} \ + -H "x-api-key: YOUR_API_KEY" +``` + +### Enable a Chainhook + +```bash +curl -X PATCH https://api.testnet.hiro.so/chainhooks/v1/me/{uuid}/enabled \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"enabled": true}' +``` + +### Delete a Chainhook + +```bash +curl -X DELETE https://api.testnet.hiro.so/chainhooks/v1/me/{uuid} \ + -H "x-api-key: YOUR_API_KEY" +``` + +### Evaluate Against a Block + +Test your chainhook against a specific block: + +```bash +curl -X POST https://api.testnet.hiro.so/chainhooks/v1/me/{uuid}/evaluate \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"block_height": 150000}' +``` + +### Bulk Enable/Disable + +Enable or disable multiple chainhooks matching filters: + +```bash +curl -X PATCH https://api.testnet.hiro.so/chainhooks/v1/me/enabled \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "enabled": false, + "filters": { + "webhook_url": "https://old-endpoint.com/webhooks" + } + }' +``` + +## Rate Limits + +The Chainhooks API enforces rate limits based on your subscription tier: + +- Free tier: 100 requests per minute +- Pro tier: 1000 requests per minute +- Enterprise: Custom limits + +When rate limited, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your application: + +```javascript +async function makeRequestWithRetry(url, options, maxRetries = 3) { + for (let i = 0; i < maxRetries; i++) { + const response = await fetch(url, options); + + if (response.status === 429) { + const delay = Math.pow(2, i) * 1000; + await new Promise(resolve => setTimeout(resolve, delay)); + continue; + } + + return response; + } + + throw new Error('Max retries exceeded'); +} +``` + +## Webhook Security + +### Consumer Secret + +When you register a chainhook, webhook payloads include an `x-chainhook-consumer-secret` header. Validate this secret in your webhook endpoint: + +```javascript +app.post('/webhooks', (req, res) => { + const receivedSecret = req.headers['x-chainhook-consumer-secret']; + const expectedSecret = process.env.CHAINHOOK_CONSUMER_SECRET; + + if (receivedSecret !== expectedSecret) { + return res.status(401).send('Unauthorized'); + } + + // Process webhook payload + res.sendStatus(200); +}); +``` + +### Rotate Secret + +Periodically rotate your consumer secret: + +```bash +curl -X POST https://api.testnet.hiro.so/chainhooks/v1/me/secret \ + -H "x-api-key: YOUR_API_KEY" +``` + +Store the new secret securely and update your webhook endpoint. + +## Best Practices + +1. **Start on testnet** - Always test chainhooks on testnet before mainnet +2. **Enable gradually** - Create chainhooks disabled, test with `evaluate`, then enable +3. **Handle errors** - Implement proper error handling and retries +4. **Validate webhooks** - Always verify the consumer secret header +5. **Use HTTPS** - Webhook URLs must use HTTPS for security +6. **Monitor usage** - Track API usage to stay within rate limits +7. **Version control** - Document your chainhook configurations +8. **Clean up** - Delete unused chainhooks to reduce costs + +## Pagination + +List endpoints support pagination via query parameters: + +```bash +# Get first page (default: 20 results) +curl "https://api.testnet.hiro.so/chainhooks/v1/me/?limit=20&offset=0" \ + -H "x-api-key: YOUR_API_KEY" + +# Get next page +curl "https://api.testnet.hiro.so/chainhooks/v1/me/?limit=20&offset=20" \ + -H "x-api-key: YOUR_API_KEY" +``` + +Response includes pagination metadata: + +```json +{ + "limit": 20, + "offset": 0, + "total": 45, + "results": [...] +} +``` + +## Next Steps + +- [API Reference](https://docs.hiro.so/en/apis/chainhooks-api/reference/chainhooks): Complete endpoint documentation +- [Filter Reference](https://docs.hiro.so/en/tools/chainhooks/reference/filters): Event filter syntax diff --git a/docs/reference/api/signer-metrics-api/README.md b/docs/reference/api/signer-metrics-api/README.md new file mode 100644 index 0000000000..d7801d03f9 --- /dev/null +++ b/docs/reference/api/signer-metrics-api/README.md @@ -0,0 +1,46 @@ +# Signer Metrics API + +Monitor and analyze signer behavior on the Stacks network via REST. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/signer-metrics-api). +{% endhint %} + +## Overview + +The Signer Metrics API provides comprehensive monitoring capabilities for signers on the Stacks network through a REST interface. Built for network analysis and performance tracking, it delivers detailed information about active signers, block acceptance rates, and timing metrics across PoX cycles. + +## Key features + +- **Signer monitoring** - Track active signers and their performance metrics +- **Block analysis** - Aggregated signer information for block validation +- **PoX cycle tracking** - Monitor signer participation across cycles + +## Usage + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' -H 'Accept: application/json' +``` + +For more usage examples, click [here](usage.md). + +## API Reference + +{% hint style="info" %} +For the complete interactive API reference, see the [Signer Metrics API Reference on Hiro Docs](https://docs.hiro.so/en/apis/signer-metrics-api/reference/signers). +{% endhint %} + +### Available Endpoints + +| Endpoint | Description | +|----------|-------------| +| Block proposals | Retrieve block proposal data for signers | +| Blocks | Get aggregated signer information for blocks | +| Info/status | Check the API status and info | +| PoX cycle signer | Get metrics for a specific signer in a PoX cycle | +| PoX cycle signers | List all signers and their metrics for a PoX cycle | + +{% hint style="info" %} +### Need help building with the Signer Metrics API? +Reach out to us on the **#api** channel on [Discord](https://stacks.chat/) under the Hiro Developer Tools section. There's also a [weekly office hours](https://www.addevent.com/event/kI22007085) call every Wednesday at 1pm ET. +{% endhint %} diff --git a/docs/reference/api/signer-metrics-api/usage.md b/docs/reference/api/signer-metrics-api/usage.md new file mode 100644 index 0000000000..377df8e1bd --- /dev/null +++ b/docs/reference/api/signer-metrics-api/usage.md @@ -0,0 +1,50 @@ +# Usage + +Learn the basics of using the Signer Metrics API. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/signer-metrics-api/usage). +{% endhint %} + +## Usage + +The Signer Metrics API is built on REST principles, enforcing HTTPS for all requests to ensure data security, integrity, and privacy. + +### Base URL + +``` +https://api.hiro.so +``` + +### Making requests + +To make a request to the Signer Metrics API, you can paste the curl command below in your terminal. + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' \ + -H 'Accept: application/json' +``` + +### Authentication + +If you are using an api-key, replace `$HIRO_API_KEY` with your secret API key. + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' \ + -H 'Accept: application/json' \ + -H 'x-api-key: $HIRO_API_KEY' +``` + +## Response codes + +The Signer Metrics API uses standard HTTP response codes to indicate request success or failure. + +| Code | Description | +|------|-------------| +| `200` | Successful request | +| `400` | Check that the parameters were correct | +| `401` | Missing API key | +| `403` | Invalid API key | +| `404` | Resource not found | +| `429` | Rate limit exceeded | +| `5xx` | Server errors | diff --git a/docs/reference/api/token-metadata-api/README.md b/docs/reference/api/token-metadata-api/README.md new file mode 100644 index 0000000000..0d7d18647f --- /dev/null +++ b/docs/reference/api/token-metadata-api/README.md @@ -0,0 +1,50 @@ +# Token Metadata API + +Fast, reliable metadata for Stacks tokens via REST. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/token-metadata-api). +{% endhint %} + +## Overview + +The Token Metadata API provides comprehensive metadata for tokens on the Stacks blockchain through a high-performance REST interface. Built with cached responses and optimized indexing, it delivers fungible token information, NFT properties, and collection data with minimal latency. + +## Key features + +- **Complete token coverage** - Metadata for fungible, non-fungible, and semi-fungible tokens +- **Cached responses** - Optimized performance through intelligent caching strategies +- **Rich metadata** - Token properties, attributes, and collection information + +## Usage + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' -H 'Accept: application/json' +``` + +For more usage examples, click [here](usage.md). + +{% hint style="info" %} +All Token Metadata API responses include rate limit headers that help you monitor your API usage with Stacks-specific quota information. +{% endhint %} + +## API Reference + +{% hint style="info" %} +For the complete interactive API reference, see the [Token Metadata API Reference on Hiro Docs](https://docs.hiro.so/en/apis/token-metadata-api/reference/tokens). +{% endhint %} + +### Available Endpoints + +| Endpoint | Description | +|----------|-------------| +| Info/status | Check the API status and info | +| Fungible tokens | List all fungible tokens with metadata | +| FT metadata | Get metadata for a specific fungible token | +| NFT metadata | Get metadata for a specific non-fungible token | +| SFT metadata | Get metadata for a specific semi-fungible token | + +{% hint style="info" %} +### Need help building with the Token Metadata API? +Reach out to us on the **#api** channel on [Discord](https://stacks.chat/) under the Hiro Developer Tools section. There's also a [weekly office hours](https://www.addevent.com/event/kI22007085) call every Wednesday at 1pm ET. +{% endhint %} diff --git a/docs/reference/api/token-metadata-api/usage.md b/docs/reference/api/token-metadata-api/usage.md new file mode 100644 index 0000000000..3859432720 --- /dev/null +++ b/docs/reference/api/token-metadata-api/usage.md @@ -0,0 +1,50 @@ +# Usage + +Learn the basics of using the Token Metadata API. + +{% hint style="info" %} +This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/apis/token-metadata-api/usage). +{% endhint %} + +## Usage + +The Token Metadata API is built on REST principles, enforcing HTTPS for all requests to ensure data security, integrity, and privacy. + +### Base URL + +``` +https://api.hiro.so +``` + +### Making requests + +To make a request to the Token Metadata API, you can paste the curl command below in your terminal. + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' \ + -H 'Accept: application/json' +``` + +### Authentication + +If you are using an api-key, replace `$HIRO_API_KEY` with your secret API key. + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' \ + -H 'Accept: application/json' \ + -H 'x-api-key: $HIRO_API_KEY' +``` + +## Response codes + +The Token Metadata API uses standard HTTP response codes to indicate request success or failure. + +| Code | Description | +|------|-------------| +| `200` | Successful request | +| `400` | Check that the parameters were correct | +| `401` | Missing API key | +| `403` | Invalid API key | +| `404` | Resource not found | +| `429` | Rate limit exceeded | +| `5xx` | Server errors |