> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with the Sharpe API in minutes. Make your first request and understand the response format.

This guide will get you up and running with the Sharpe API. You will make your first request, understand the response envelope format, and learn how errors are returned.

> [!NOTE]
>
> You need an API key. Create one from the
> [API key dashboard](https://www.sharpe.ai/dashboard/api-keys): a new account gets a one-time
> trial of 7 days and 250 requests, and after it the key needs a plan from
> [/dashboard/billing](https://www.sharpe.ai/dashboard/billing) (from \$29/month). Store the key as
> `SHARPE_API_KEY`.

## Make your first request

Authenticated API requests use the versioned `https://www.sharpe.ai/api/v1/` prefix and require an `Authorization` header. Here is how to fetch current funding rates:

`GET /v1/funding/rates?type=current`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/funding/rates \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d type=current
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/funding/rates?type=current',
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const data = await res.json()
console.log(data)
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/funding/rates",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"type": "current"},
)
data = resp.json()
print(data)
```

## Response envelope

Every successful response wraps data in a consistent envelope:

```json Success response theme={null}
{
  "data": [
    {
      "exchange": "Binance",
      "symbol": "BTCUSDT",
      "base_coin": "BTC",
      "rate": 0.0001,
      "interval_hours": 8,
      "next_funding_time": "2026-03-27T08:00:00Z",
      "updated_at": "2026-03-27T07:45:00Z"
    },
    {
      "exchange": "Bybit",
      "symbol": "BTCUSDT",
      "base_coin": "BTC",
      "rate": 0.00012,
      "interval_hours": 8,
      "next_funding_time": "2026-03-27T08:00:00Z",
      "updated_at": "2026-03-27T07:44:30Z"
    }
  ],
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-27T07:45:00Z",
    "elapsed_ms": 85
  }
}
```

The `exchange` field carries the venue display name (`Binance`, `Gate.io`), not a lowercase slug. Match on these values when filtering client-side.

The envelope always contains:

* **`data`**: the requested payload (shape varies by endpoint)
* **`meta`**: request metadata with `request_id`, `timestamp`, and `elapsed_ms`

## Error format

When something goes wrong, the API returns a flat [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem detail object:

```json Error response theme={null}
{
  "type": "https://www.sharpe.ai/errors/invalid_parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Invalid parameter \"type\": Invalid enum value. Expected 'current' | 'accumulated' | 'history'",
  "request_id": "req_abc123def456ghij",
  "doc_url": "https://www.sharpe.ai/docs/errors#error-codes",
  "suggested_action": "Check the parameter value against the endpoint documentation. Use GET /v1/futures/coins or GET /v1/meta/coverage to discover valid values."
}
```

[Read the full error reference](https://docs.sharpe.ai/errors.md)

## Common use cases

Common ways developers use the Sharpe API:

### Monitor funding rates for arbitrage

Fetch `type=current` to scan for outlier funding rates, then use `type=accumulated` to see whether the rate has been persistently positive or negative over 7 to 30 days. Pair with the [spot-perp arbitrage](https://docs.sharpe.ai/arbitrage-spot-perp.md) endpoint to surface opportunities automatically.

### Build a market heatmap

Call the [heatmap](https://docs.sharpe.ai/heatmap.md) endpoint with `mode=coins` and a category like `layer-1` or `meme-token` to get performance data across multiple timeframes in a single request. Each dot includes 24h, 7d, 30d, 1y, and 3y returns.

### Portfolio correlation analysis

Use the [correlation](https://docs.sharpe.ai/correlation.md) endpoint with a mix of crypto IDs and TradFi IDs (e.g., `bitcoin,ethereum,sp500,gold`) to compute a correlation matrix. Choose a `period` of `90d` or `1y` to match your rebalancing horizon.

### Track narrative rotation

The [narratives](https://docs.sharpe.ai/narratives.md) and [ecosystems](https://docs.sharpe.ai/ecosystems.md) endpoints return aggregated market cap, volume, and performance for sector-level groupings. Compare narrative-level 24h and 7d changes to spot which sectors capital is rotating into.

## Best practices

* **Cache intentionally.** Most endpoints return data that updates on a known schedule (current funding rates refresh every 5 minutes and heatmap data every 3 hours). Cache locally and respect `Cache-Control` headers to avoid burning quota.
* **Use bulk responses.** Endpoints like `/v1/funding/rates?type=current` return all symbols at once. Fetch once and filter client-side rather than making per-symbol requests.
* **Handle 429s gracefully.** Read the `X-RateLimit-Reset` header (a Unix timestamp) and wait until that time before retrying. See the [rate limits guide](https://docs.sharpe.ai/rate-limits.md) for details.
* **Include `X-Request-Id` in support tickets.** Every response includes this header. It lets us trace your exact request through our infrastructure.
* **Use separate keys per environment.** Create distinct API keys for development, staging, and production so you can rotate or revoke them independently.

## What's next?

* [Learn about authentication and API key management](https://docs.sharpe.ai/authentication.md)
* [See the plans, rate limits and quotas](https://docs.sharpe.ai/rate-limits.md)
* [Explore funding rates endpoints](https://docs.sharpe.ai/funding-rates.md)
* [Read the full error reference](https://docs.sharpe.ai/errors.md)
* [Download the Postman collection](https://www.sharpe.ai/sharpe-api.postman_collection.json)
* [View the OpenAPI spec](https://www.sharpe.ai/openapi.json)
* [LLM-friendly API reference](https://www.sharpe.ai/llms.txt)
* [Developer tools and SDKs](https://docs.sharpe.ai/developer-tools.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.