Basic usage

Usage

The Stacks Node RPC API provides direct access to Stacks blockchain nodes through RPC endpoints. All requests use HTTPS and enforce standard REST principles.

Base URL

https://api.hiro.so

Making requests

Terminal

$ curl -L 'https://api.hiro.so/v2/info' \
  -H 'Accept: application/json'

Authentication

Include your API key for higher rate limits:

Terminal

$ curl -L 'https://api.hiro.so/v2/info' \
  -H 'Accept: application/json' \
  -H 'x-api-key: $HIRO_API_KEY'

Rate limits

RPC calls are weighted based on method cost and consume more units than REST endpoints:

Method Type	Examples	Cost Multiplier
Light reads	`get_block`, `get_transaction`	1×
Read-only contract calls	`call_read_only_function`	2×
Transaction submission	`submit_transaction`	3×
Heavy operations	`trace_call`, deep contract scans	5×

Rate limit headers

X-RateLimit-Limit: 900              # window capacity in units
X-RateLimit-Remaining: 125          # remaining units
X-RateLimit-Reset: 60               # seconds until reset
X-RateLimit-Method-Cost: 3          # cost for this RPC method
X-Plan-Tier: starter                # your plan tier
X-Surface: rpc                      # indicates RPC endpoint

Response codes

Code	Description
`200`	Successful request
`400`	Invalid parameters
`401`	Missing API key
`403`	Invalid API key
`404`	Resource not found
`429`	Rate limit exceeded
`5xx`	Server/upstream node errors