Skip to main content

Getting Started

This guide takes you from an empty project to a running OvercastApp that can read the market, move funds in and out of your escrow vault, and talk to the RFQ channel.

Prerequisites​

  • Node.js ≥ 20 and a package manager (npm, pnpm, or yarn).
  • A Solana wallet keypair (e.g. a standard id.json from solana-keygen).
  • An Overcast API key — the backend rejects unauthenticated calls, so every app needs one, including read-only ones. See Getting an API key below.
  • Access to a Solana RPC endpoint and an Overcast backend. For local development the defaults are https://rpc.sandbox.overcast.xyz (RPC) and https://api.sandbox.overcast.xyz (backend).

Getting an API key​

Access is granted per app, so the first key is issued by us:

  1. Request a login. Reach out to the Overcast team (info@overcast.xyz) and ask for access. We create your login for the Overcast web app.

  2. Sign in to the web app following the steps you'll receive.

  3. Create an API key under Profile → API keys.

  4. Store it as an environment variable so it never lands in your source:

    export OVERCAST_API_KEY=<your-api-key>

Install​

The packages are published to npm. Add core and the Solana client to your project:

npm install @overcast-xyz/core @overcast-xyz/solana-client

Or with your package manager of choice:

pnpm add @overcast-xyz/core @overcast-xyz/solana-client
yarn add @overcast-xyz/core @overcast-xyz/solana-client

Create an OvercastApp​

OvercastApp is the single entry point to the SDK. You hand it a chain-specific factory — SolanaFactory — and get back one object that carries every capability:

import { OvercastApp } from "@overcast-xyz/core";
import { SolanaFactory } from "@overcast-xyz/solana-client";

const factory = new SolanaFactory({
  rpcUrl: "http://127.0.0.1:8899", // Solana RPC
  backend: "http://127.0.0.1:3000", // Overcast backend (REST + RFQ socket)
  apiKey: process.env.OVERCAST_API_KEY, // currently required — authenticates the backend calls
  privateKey: process.env.OVERCAST_KEYPAIR, // path, base58, or JSON byte array
});

const app = await OvercastApp.create({ factory });

console.log("wallet:", app.publicKey);

apiKey is currently required: it is sent as a bearer token on every REST read and as the auth token on the RFQ socket handshake. Without it the backend answers 401 and the socket refuses to connect — so app.api and app.rfq are dead even in read-only mode.

privateKey accepts the same formats everywhere in the SDK and CLI: a raw byte array, the contents of a Solana id.json, or a base58-encoded secret key. Omit it entirely for a read-only app — everything works except signing (writes and RFQ). Note that read-only still means "API key, no wallet": the key is what the backend authenticates, the keypair is what signs.

Make your first calls​

Read the market​

// Curated, off-chain views from the backend:
const options = await app.api.listOptions({});

// Curated asset metadata for this chain, resolved for slot lookups:
const assets = await app.assets();

// Direct on-chain reads:
const balance = await app.chain.balance(app.publicKey, assets.list()[0]);

Fund your escrow vault​

All protocol payments (premiums, collateral, settlement) flow through your on-chain escrow vault, not your wallet directly. Deposit before you trade:

const { hashes } = await app.chain.deposit({
  depositor: app.publicKey,
  mint: cashMint, // any asset address; assets.bySymbol("USDC") finds a curated one
  amount: 1_000_000_000n, // native units, as bigint
});
console.log("deposited, tx", hashes);

Withdrawing is symmetric:

await app.chain.withdraw({
  withdrawer: app.publicKey,
  mint: cashMint,
  amount: 500_000_000n,
});

Connect to the RFQ channel​

The RFQ socket is lazy — it only connects the first time you touch app.rfq (and requires a signer):

const rfq = app.rfq;
await rfq.registerRole("MAKER"); // or "TAKER"

rfq.onNewQuote = (quote) => console.log("quote received:", quote.quoteId);

const { rfqId } = await rfq.createRfq({
  creator: app.publicKey,
  request: { details }, // partial OptionDetails — everything except the premium
  side: "MAKER",
});

What details looks like, who quotes whom, and how a quote becomes an on-chain option is the subject of the next two guides:

Amounts, IDs, and other conventions​

A few conventions apply across the whole SDK:

  • Amounts are bigint in native units (the asset's smallest unit) in all canonical types. On the wire (socket + REST) they travel as decimal strings; the SDK converts for you. Helpers: parseUnits, formatUnits, toNativeAmount, toDisplayAmount.
  • IDs are base58 strings (Id). Offers and options are content-addressed: their ID is the sha256 of a canonical byte encoding, computed by getId and byte-for-byte identical to the on-chain program's hashing.
  • Two signers exist. The chain signer signs Solana transactions; the protocol signer (Ed25519ProtocolSigner) signs offer IDs for the RFQ flow. Both are derived from privateKey unless you override them.