Agents & automation

**OwlViz is agent-ready infrastructure** — normalized Solana asset and collection intelligence you can call from autonomous agents, LLM tools, and workflows. OwlViz does **not** execute trades, run strategies, sign transactions, or provide investment advice.

Human-oriented guides: [Quick start](./quickstart.md) · [Authentication](./authentication.md) · [Errors & limits](./errors-and-rate-limits.md)

Machine-readable spec

Use the **Automation** tag in OpenAPI to filter market events, Market Watch, and webhook routes. Regenerate clients with any OpenAPI 3.1 codegen (e.g. openapi-generator, Speakeasy, Stainless), or use the official **[@owlviz/sdk](./getting-started.md)** TypeScript client (v1 routes, 1:1 with OpenAPI).

Base URL & auth

https://api.owlviz.dev

Keys are issued once in the [developer portal](https://owlviz.dev/developer/projects) (ov_live_ prefix). Raw secrets are shown **once** at creation.

Rate limits (60s fixed window)

Keyed traffic buckets by API key ID; anonymous traffic uses Free tier **per IP**. On 429, honor Retry-After and X-RateLimit-* headers. Details: [errors-and-rate-limits.md](./errors-and-rate-limits.md).

Example mint (The Bullpen): C5gHBKXwA8jduXNk3HyAVLnLBN6PEM8fTqkNNh5uyyjJ

Recommended call flow for agents

1. **Health** — GET /health (cheap sanity check).

2. **Asset context** — GET /v1/assets/{mint} for normalized metadata, health, inspection, and collection linkage.

3. **Collection market** — GET /v1/collections/{address}/market for multi-provider spot floors; GET .../market/reference for rolling reference floor and movement vs spot; GET .../market/state for a **single combined snapshot** (spot, reference, 1h/24h change, coverage) when you do not want to merge multiple responses ([market-state.md](./market-state.md)).

4. **Observation history** — GET /v1/collections/{address}/market/history for bucketed spot/reference/provider series from persisted observations ([market-history.md](./market-history.md)).

5. **Events (pull)** — GET /v1/market-events or GET /v1/collections/{address}/market/events with since, eventType, and cursor pagination.

6. **Events (push)** — create a **Market Watch** (continuous sampling) and a **webhook** subscription for floor/market event types (see below).

OwlViz returns JSON with a top-level data object on success and { error: { code, message } } on failure.

Key endpoints (agent cheat sheet)

Change **monitor** automation (POST /v1/monitors, portal /developer/change-monitors) is self-serve with plan quotas; manual check remains admin-only — not required for floor/market automation alone.

Minimal examples

Health

curl -sS "https://api.owlviz.dev/health" -H "Accept: application/json"

{"status":"ok","service":"owlviz-api","timestamp":"2026-01-01T00:00:00.000Z"}

Asset (with API key)

curl -sS \
  "https://api.owlviz.dev/v1/assets/C5gHBKXwA8jduXNk3HyAVLnLBN6PEM8fTqkNNh5uyyjJ" \
  -H "Authorization: Bearer ov_live_<secret>" \
  -H "Accept: application/json"

Collection floor + reference

COLLECTION="<canonical-collection-address>"
curl -sS "https://api.owlviz.dev/v1/collections/${COLLECTION}/market" -H "Accept: application/json"
curl -sS "https://api.owlviz.dev/v1/collections/${COLLECTION}/market/reference?window=15m" \
  -H "Accept: application/json"

Poll market events

curl -sS \
  "https://api.owlviz.dev/v1/market-events?eventType=spot_floor_changed&limit=10" \
  -H "Accept: application/json"

Paginate with pagination.nextCursor when present.

Webhooks recipe (agents)

Push delivery avoids polling. Full contract: [monitoring.md](./monitoring.md#webhooks) and repo [webhooks.md](../webhooks.md) (payload + HMAC details).

1. Subscribe (API key)

curl -sS -X POST "https://api.owlviz.dev/v1/webhooks" \
  -H "Authorization: Bearer ov_live_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.example.com/owlviz/events",
    "events": ["spot_floor_changed", "reference_floor_changed"]
  }'

Store the returned **secret** immediately — it is not shown again. Use wildcard "events": ["*"] only if you intend to receive all event types.

2. Verify HMAC (required)

OwlViz signs the **exact raw JSON body** with HMAC-SHA256:

signature = HMAC_SHA256(secret, timestamp + "." + rawBody)

Headers: X-Metadata-Timestamp, X-Metadata-Signature, X-Metadata-Event, X-Metadata-Delivery.

Reject requests when the timestamp skew exceeds your tolerance (e.g. 5 minutes). Use constant-time comparison for the signature.

3. Handle idempotently

Delivery is **at-least-once**. Retries may repeat the same logical event.

• Dedupe on payload.id (source event UUID) and/or X-Metadata-Delivery (delivery row UUID).
• Return **2xx** only after your handler has safely recorded the event (queue, DB upsert, etc.).
• Return **4xx** for permanent receiver errors so OwlViz does not retry indefinitely (see [webhooks.md](../webhooks.md)).

Market events use **WebhookPayloadV1** (version: "1") with before / after lane snapshots; monitor events include diff. Synthetic tests set test: true.

4. Optional: Market Watch

Continuous sampling emits richer market events. Create a watch, then rely on webhooks or poll GET /v1/market-events:

curl -sS -X POST "https://api.owlviz.dev/v1/market-watches" \
  -H "Authorization: Bearer ov_live_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"collectionAddress":"<address>","intervalSeconds":120}'

Plan quotas cap active watches — see [developer-plans](./developer-plans.md) (portal UI: /developer/market-watches).

What OwlViz is not

• Not a trading or backtesting engine
• Not wallet signing or transaction submission
• Not a price oracle or “buy/sell” signal service

Use OwlViz as **structured context** (metadata health, floors, reference movement, durable events) inside your own agent logic.