Create a watchlist entry

A watchlist entry subscribes Triport to on-chain changes for a single Solana account and forwards every observed change to a delivery target you control. When the watched account's data changes at the requested commitment level, Triport pushes an event either to your HTTPS webhook (callback_type: webhook) or over the live WebSocket channel (callback_type: ws).

Use this endpoint to build account-change notifications without holding an open subscription yourself — Triport maintains the upstream subscription and the delivery fan-out on your behalf. Each call creates one entry for one pubkey; call it repeatedly to watch multiple accounts. The created entry is scoped to your tenant (derived from the authenticated API key) and is returned with a server-generated id you use to fetch or delete it later.

Gotchas:

• callback_type: telegram is reserved and not yet accepted — sending it returns 400 invalid_params.
• For callback_type: ws, the callback_url is treated as a client-side identifier (the channel to associate the entry with), not an HTTP destination. Events are delivered over the live WebSocket channel rather than pushed to a URL.
• commitment defaults to confirmed when omitted.

This endpoint takes a JSON request body (Content-Type: application/json).

201 Created

All errors use the shared error envelope (error, message, request_id). See errors for the full schema, the 403 tier-upgrade fields, and the 429 Retry-After / X-RateLimit-* headers.

Example 403:

{
  "error": "tier_insufficient",
  "message": "sol_watchlist requires the business tier",
  "request_id": "req_9c1f7a",
  "current_tier": "pro",
  "required_tier": "business",
  "category": "sol_watchlist"
}

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/sol/watchlist", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pubkey: "So11111111111111111111111111111111111111112",
    callback_type: "webhook",
    callback_url: "https://hooks.example.com/sol/account-change",
    commitment: "confirmed",
  }),
});


if (!res.ok) throw new Error(`watchlist create failed: ${res.status}`);
const entry = await res.json();
console.log(entry.id); // 8f1d6c2a-...

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const client = new Triport({ apiKey: process.env.TRIPORT_API_KEY! });


const entry = await client.sol.watchlist.create({
  pubkey: "So11111111111111111111111111111111111111112",
  callbackType: "webhook",
  callbackUrl: "https://hooks.example.com/sol/account-change",
  commitment: "confirmed",
});


console.log(entry.id, entry.createdAt);

Python (triport-sdk)

import os
from triport import Triport


client = Triport(api_key=os.environ["TRIPORT_API_KEY"])


entry = client.sol.watchlist.create(
    pubkey="So11111111111111111111111111111111111111112",
    callback_type="webhook",
    callback_url="https://hooks.example.com/sol/account-change",
    commitment="confirmed",
)


print(entry.id, entry.created_at)

• Manage entries: list all of your entries with GET /v1/sol/watchlist, fetch one with GET /v1/sol/watchlist/{id}, and remove one with DELETE /v1/sol/watchlist/{id} (idempotent — a repeat delete returns 404).
• Capacity: the Business tier allows up to 10,000 watched pubkeys per tenant. Creating beyond your cap is rejected.
• WebSocket delivery: when callback_type is ws, connect to the live watchlist push channel to receive events for entries created under your key; the entry's callback_url ties the entry to your channel.
• Commitment trade-off: processed is fastest but may be rolled back; finalized is safest but lags. confirmed (the default) balances the two.