Surge Subscription Guide

This guide explains how to subscribe to Switchboard Surge programmatically on Solana, without using the explorer UI. It is intended for AI agents, bots, and automated systems that need to create or manage Surge subscriptions via on-chain transactions.

Overview

Surge subscriptions are managed entirely on Solana via the Surge program (orac1eFjzWL5R3RbbdMV68K9H6TaCVVcL6LjvQQWAbz). The subscription flow is:

1. Choose a tier

2. Acquire SWTCH tokens

3. Call subscription_init with a live SWTCH/USDT oracle quote

4. Program calculates cost in SWTCH at the live price, transfers tokens to the vault

5. Subscription PDA is created and active until the end epoch

Wallet (has SWTCH tokens)
  → picks tier (Plug / Pro / Enterprise)
  → calls subscription_init with a fresh SWTCH/USDT oracle quote
  → program calculates cost in SWTCH at live price
  → transfers SWTCH to vault
  → subscription PDA created, active until end epoch

---

Step 1: Choose a Tier

Tiers are on-chain PDA accounts with the seed [TIER, tier_id_bytes], created by Switchboard admins. Each tier defines:

Field	Description
cost_per_epoch_usd_cents	Price in USD cents per epoch
max_connections	Maximum concurrent WebSocket connections
max_feeds	Maximum feeds per subscription
max_feeds_per_ix	Maximum feeds per instruction
min_delay_ms	Minimum update delay in milliseconds
is_public	Whether anyone can subscribe

Public tiers (tier IDs 1-9) are open to all wallets. Tier IDs 10+ require admin approval.

Current Tiers

Tier	Tier ID	Approx. Cost	Quote Interval	Max Feeds	Max Connections
Plug	1	Free	10s	2	1
Pro	2	~$3,000/mo	450ms	100	10
Enterprise	3	~$7,500/mo	0ms	300	15

To read tier details on-chain, derive the tier PDA:

const [tierPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("TIER"), new BN(tierId).toArrayLike(Buffer, "le", 4)],
  SURGE_PROGRAM_ID
);

---

Step 2: Get SWTCH Tokens

All subscription payments must be in SWTCH tokens. The program enforces this check:

require!(payment_mint.key() == state.swtch_mint, SubscriberError::MustPayWithSwtch);

Acquire SWTCH tokens via any Solana DEX (e.g., Jupiter, Raydium) before initiating the subscription.

---

Step 3: Call subscription_init

Send a transaction with the subscription_init instruction. The instruction takes the following parameters:

Parameters

Parameter	Type	Description
tier_id	u32	Which tier to subscribe to (e.g., 1, 2, 3)
epoch_amount	u16	Number of epochs to pay for (1-146, i.e., up to ~1 year)
contact_name	Option<String>	Optional contact name metadata
contact_email	Option<String>	Optional contact email metadata

Required Accounts

Account	Description	Derivation
State	The program's global state PDA	Seed: [STATE]
Tier	The chosen tier's PDA	Seed: [TIER, tier_id_bytes]
Owner	The wallet subscribing	Your wallet pubkey
Payer	Signer paying for rent + SWTCH tokens	Typically same as owner
Payment Mint	The SWTCH token mint	Stored in state.swtch_mint
Payer Token Account	Payer's SWTCH associated token account	Standard ATA derivation
Token Vault	Program's vault for the payment mint	PDA from program state
Quote Account	A Switchboard oracle quote with the live SWTCH/USDT price	Fetched from Switchboard oracle

Deriving PDAs

import { PublicKey } from "@solana/web3.js";
import BN from "bn.js";

const SURGE_PROGRAM_ID = new PublicKey("orac1eFjzWL5R3RbbdMV68K9H6TaCVVcL6LjvQQWAbz");

// State PDA
const [statePda] = PublicKey.findProgramAddressSync(
  [Buffer.from("STATE")],
  SURGE_PROGRAM_ID
);

// Tier PDA (e.g., tier_id = 2 for Pro)
const tierId = 2;
const [tierPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("TIER"), new BN(tierId).toArrayLike(Buffer, "le", 4)],
  SURGE_PROGRAM_ID
);

// Subscription PDA (derived from owner wallet)
const [subscriptionPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("SUBSCRIPTION"), ownerPublicKey.toBuffer()],
  SURGE_PROGRAM_ID
);

---

Step 4: On-Chain Pricing

The program does not use a hardcoded SWTCH price. Instead, it reads the live SWTCH/USDT price from a Switchboard oracle quote passed as an account in the transaction.

Pricing Logic

1. Deserializes the oracle quote account

2. Validates the feed ID matches the expected swtch_feed_id stored in program state

3. Extracts the USD price (e.g., $0.11246 per SWTCH)

4. Converts tier cost from USD cents to SWTCH lamports:

lamports = (0.01 / swtch_price) * 1e9

1. Multiplies by epoch_amount * cost_per_epoch_usd_cents

2. Transfers that amount of SWTCH from payer's token account to the program vault

Example Cost Calculation

For a Pro tier at cost_per_epoch_usd_cents = 700 (i.e., $7.00/epoch), buying 40 epochs, with SWTCH at $0.11:

cost_per_cent_in_lamports = (0.01 / 0.11) * 1e9 = 90,909,090 lamports
total = 90,909,090 * 40 * 700 = 2,545,454,520,000,000 lamports

The oracle quote must be fresh — stale quotes will be rejected.

---

Step 5: Subscription Created

Once the transaction succeeds, a subscription PDA is created at [SUBSCRIPTION, owner_pubkey]. The subscription includes:

• Bonus epoch: The current epoch is free — you get +1 epoch on top of what you paid for

• Epoch tracking: Subscription validity is tracked via subscription_start_epoch and subscription_end_epoch

• User management: Up to 16 authorized users can be added later via subscription_manage_users

---

Providing the Oracle Quote

The SWTCH/USDT price quote is the most important piece of the subscription transaction. You need to pass a valid, fresh Switchboard oracle quote for the SWTCH/USDT feed.

Using the Switchboard SDK

import * as sb from "@switchboard-xyz/on-demand";

const { keypair, connection, program } = await sb.AnchorUtils.loadEnv();
const queue = await sb.Queue.loadDefault(program!);
const crossbar = new sb.Crossbar({
  rpcUrl: connection.rpcEndpoint,
  programId: queue.pubkey,
});

// Fetch the SWTCH/USDT oracle quote
// The swtch_feed_id is stored in the program state account
const swtchFeedHash = "<SWTCH/USDT feed hash from program state>";
const quoteIx = await queue.fetchQuoteIx(crossbar, [swtchFeedHash], {
  numSignatures: 1,
  payer: keypair.publicKey,
});

Include the quote instruction(s) in the same transaction as subscription_init to ensure the price data is fresh and verified.

---

Full Transaction Assembly

A complete subscription transaction includes:

1. Oracle quote verification instruction(s) — ensures fresh SWTCH/USDT price on-chain

2. subscription_init instruction — creates the subscription using the verified price

import * as sb from "@switchboard-xyz/on-demand";
import { Connection, Keypair, PublicKey } from "@solana/web3.js";

// 1. Setup
const { keypair, connection, program } = await sb.AnchorUtils.loadEnv();
const queue = await sb.Queue.loadDefault(program!);
const crossbar = new sb.Crossbar({
  rpcUrl: connection.rpcEndpoint,
  programId: queue.pubkey,
});

// 2. Fetch SWTCH/USDT oracle quote instructions
const swtchFeedHash = "<SWTCH/USDT feed hash>";
const quoteIxs = await queue.fetchQuoteIx(crossbar, [swtchFeedHash], {
  numSignatures: 1,
  payer: keypair.publicKey,
});

// 3. Build subscription_init instruction
//    (using the Surge program's IDL / client)
const subscriptionInitIx = buildSubscriptionInitIx({
  tierId: 2,           // Pro tier
  epochAmount: 40,     // ~40 epochs
  contactName: null,
  contactEmail: null,
  accounts: {
    state: statePda,
    tier: tierPda,
    owner: keypair.publicKey,
    payer: keypair.publicKey,
    paymentMint: swtchMint,
    payerTokenAccount: payerSwtchAta,
    tokenVault: tokenVaultPda,
    quoteAccount: quoteAccountPubkey,
  },
});

// 4. Build and send versioned transaction
const tx = await sb.asV0Tx({
  connection,
  ixs: [quoteIxs, subscriptionInitIx],
  signers: [keypair],
  lookupTables: [],
});

const sig = await connection.sendTransaction(tx);
console.log(`Subscription created: ${sig}`);

---

Verifying Your Subscription

After the transaction confirms, read the subscription PDA to verify:

const [subscriptionPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("SUBSCRIPTION"), keypair.publicKey.toBuffer()],
  SURGE_PROGRAM_ID
);

const subscriptionAccount = await program.account.subscription.fetch(subscriptionPda);
console.log("Start epoch:", subscriptionAccount.subscriptionStartEpoch.toString());
console.log("End epoch:", subscriptionAccount.subscriptionEndEpoch.toString());

---

Key Addresses

Item	Value
Surge Program ID	orac1eFjzWL5R3RbbdMV68K9H6TaCVVcL6LjvQQWAbz
SWTCH Token Mint	Stored in program state (state.swtch_mint)
SWTCH/USDT Feed ID	Stored in program state (state.swtch_feed_id)

---

Notes for AI Agents

• Fresh quotes are mandatory: The oracle quote account must contain a recent SWTCH/USDT price. Include the quote verification instruction in the same transaction.

• Epoch amounts: Valid range is 1-146 epochs. One Solana epoch is approximately 2-3 days, so 146 epochs covers roughly one year.

• Free tier: The Plug tier (tier ID 1) is free but still requires calling subscription_init with a valid oracle quote (the transfer amount will be zero).

• Subscription PDA is unique per wallet: Each wallet can have only one subscription at [SUBSCRIPTION, owner_pubkey].

• Managing users: After subscribing, use subscription_manage_users to authorize up to 16 additional wallets to use the subscription.