Getting started

This guide walks from zero to a working OwlViz integration using the official TypeScript SDK and the same v1 routes documented in [OpenAPI](https://api.owlviz.dev/openapi.json).

1. Create an API key

1. Sign in at [owlviz.dev](https://owlviz.dev).

2. Open **Developer → API keys** and create a key (ov_live_…).

3. Store it in your environment — never commit it to git.

bash

export OWLVIZ_API_KEY="ov_live_your_key_here"
export OWLVIZ_API_BASE="https://api.owlviz.dev"

Anonymous reads work for public asset and collection routes; keyed requests unlock plan RPM and automation (monitors, webhooks, Market Watch writes). See [authentication.md](./authentication.md).

With a developer API key, the first GET /v1/collections/:address or GET /v1/collections/:address/market for an **unknown** collection automatically registers it and queues one background index job (daily caps apply). Anonymous clients still receive COLLECTION_NOT_FOUND without indexing — see [collections.md](./collections.md#auto-index-on-authenticated-lookup-sprint-c27).

2. Install the SDK

From this monorepo:

bash

pnpm add @owlviz/sdk@workspace:*

From npm (recommended outside the monorepo):

bash

npm install @owlviz/sdk

Monorepo path: packages/sdk. Publish steps: [sdk-publish.md](../sdk-publish.md).

3. First request

import { OwlViz } from '@owlviz/sdk';

const client = new OwlViz({
  apiKey: process.env.OWLVIZ_API_KEY,
  baseUrl: process.env.OWLVIZ_API_BASE,
});

const mint = 'C5gHBKXwA8jduXNk3HyAVLnLBN6PEM8fTqkNNh5uyyjJ';
const asset = await client.assets.get(mint);
console.log(asset.name, asset.health);

Equivalent curl:

bash

curl -sS "$OWLVIZ_API_BASE/v1/assets/$mint" \
  -H "Authorization: Bearer $OWLVIZ_API_KEY" \
  -H "Accept: application/json"

4. Collection market

const address = 'YOUR_COLLECTION_ADDRESS';
const snapshot = await client.market.get(address);
const reference = await client.market.reference(address, { window: '15m' });
const history = await client.market.history(address, { window: '24h', metric: 'spot_floor' });

Human docs: [Collections — market](./collections.md), [Market observation history](./market-history.md).

5. Examples & agents

Resource	Location
Runnable example projects	[`examples/`](../../examples/) at repo root
curl + TS snippets	[docs/api/examples/](./examples/)
Agent / OpenAPI workflow	[agents.md](./agents.md)

Stable v1 contract

Route paths and response envelopes are frozen for SDK consumers. See [v1 API surface](./v1-api-surface.md) and [changelog](./changelog.md).

Next steps

[Quick start](./quickstart.md) — two-minute asset resolve (curl + fetch)
[Errors](./errors.md) and [rate limits](./rate-limits.md)
[Webhooks](./webhooks.md)
[Monitoring](./monitoring.md) — change monitors (keyed)