Requests
Learn how to authenticate and make requests to the Guavy API using API keys or OAuth 2 tokens.
Connecting to the API
You can authenticate requests using either your API key or an OAuth access token, depending on your use case. You should use an API key if you're writing code that tightly couples your application data to your Guavy account data; if you ever need to access someone else's Guavy account data, you should use OAuth 2.
If you're integrating with the Guavy API using one of the official client libraries, you won't need to worry about the implementation details for authentication.
Authenticate With an API Key or OAuth 2 Token
API keys and OAuth 2 tokens can be used to make authenticated requests the same way. We'll refer to both as tokens.
You can either use HTTP Basic Authentication or Bearer Authentication.
HTTP Basic Authentication:
curl \
--request GET \
--url 'https://data.guavy.com/api/v1/instruments/get-detail/BTC' \
--header 'Authorization: Bearer YOUR-GUAVY-ACCESS-TOKEN' \
--header 'Content-Type: application/json'
Token Costs
Each API call consumes tokens from your monthly budget. Endpoints that return richer or deeper data cost more tokens. Historical endpoints scale with the amount of data requested.
| Endpoint | Token Cost |
|---|---|
| GET /api/v1/ping | 1 |
| GET /api/v1/instruments/list-symbols | 1 |
| GET /api/v1/instruments/search-instruments/:query | 2 |
| GET /api/v1/instruments/get-detail/:symbol | 5 |
| GET /api/v1/instruments/scorecard/:symbol | 10 |
| GET /api/v1/newsroom/get-market-summary | 3 |
| GET /api/v1/newsroom/get-article/:id | 3 |
| GET /api/v1/newsroom/get-recent-briefs/:symbol | 3 – 8 (scales with limit) |
| GET /api/v1/newsroom/search-briefs/:symbol | 3 – 8 (scales with limit) |
| GET /api/v1/newsroom/get-instrument-analysis/:symbol | 10 |
| GET /api/v1/trades/get-recent-buys | 3 |
| GET /api/v1/trades/get-recent-sells | 3 |
| GET /api/v1/trades/get-recommendations | 5 |
| GET /api/v1/trades/get-current-action/:symbol/:strategy | 5 |
| GET /api/v1/trades/get-trend-history/:symbol/:limit | 5 – 15 (scales with limit) |
| GET /api/v1/trades/get-backtest-history/:symbol/:strategy | 8 – 20 (scales with years) |
| GET /api/v1/trades/get-backtest-summary/:symbol/:strategy | 8 – 20 (scales with years) |
| GET /api/v1/sentiment/get-sentiment-history/:symbol | 3 – 12 (scales with limit) |
| GET /api/v1/technical-analysis/get-price-history/:symbol | 5 |
| GET /api/v1/technical-analysis/get-indicators/:symbol | 8 |
Account Limits
Each plan includes a monthly token budget: 3,000 for Sandbox, 250,000 for Quant, and 2,000,000 for Commercial. You can top up at any time with a one-time token pack — unused tokens roll over every month. If you exceed your budget, the API returns a 403 until the next reset or until you purchase more tokens.
Connection Limits
The Guavy API has a limit of 10 simultaneous connections and a 120-second timeout per request. We recommend caching responses that don't change frequently to reduce token consumption and improve performance.