Skip to main content

Quick Start

Get up and running with Runner Protocol in five minutes. This guide walks you through reading auction data from the indexer API and understanding the transaction flow for bidding on devnet.

SDK Coming Soon

The @runner-protocol/sdk package is not yet publicly available. The code examples below that reference SDK imports show what will be available at mainnet launch. For now, use the Indexer API for reading auction state, or use the Runner Protocol app to participate in auctions directly.

Prerequisites​

  • Node.js 18+
  • A Solana wallet with devnet SOL (use solana airdrop 2 on devnet)
  • Basic familiarity with Solana transactions and @solana/web3.js

Install​

Once the SDK is published, it will be installed via:

npm install @runner-protocol/sdk @solana/web3.js

The SDK will have a single peer dependency on @solana/web3.js ^1.90.0.

Connect to Devnet​

import { Connection, Keypair } from "@solana/web3.js";

const connection = new Connection("https://api.devnet.solana.com", "confirmed");
const wallet = Keypair.generate(); // or load your own keypair

Read an Auction from the Indexer​

The Runner Protocol indexer exposes a public REST API. No authentication is required for read endpoints.

const INDEXER_URL = "https://cca-indexer-production.up.railway.app";

// List active auctions
const response = await fetch(`${INDEXER_URL}/api/auctions?limit=5`);
const { data, next_cursor } = await response.json();

console.log(`Found ${data.length} auctions`);
for (const auction of data) {
  console.log(`  ${auction.pubkey} - bids: ${auction.total_bids}`);
}

// Get a single auction detail
const auctionPubkey = data[0].pubkey;
const detail = await fetch(`${INDEXER_URL}/api/auctions/${auctionPubkey}`);
const auction = await detail.json();

console.log("Clearing price:", auction.clearing_price);
console.log("Total bids:", auction.total_bids);

Place a Bid​

Build and send a place_bid transaction using the SDK instruction builders.

import {
  buildPlaceBidInstruction,
  encodeQ96,
  getAssociatedTokenAddress,
  createAssociatedTokenAccountIdempotentInstruction,
  TOKEN_PROGRAM_ID,
} from "@runner-protocol/sdk";
import {
  Transaction,
  sendAndConfirmTransaction,
  PublicKey,
} from "@solana/web3.js";

const auctionConfig = new PublicKey(auctionPubkey);
const quoteMint = new PublicKey(auction.quote_mint);

// Encode your max price in Q96 format (e.g., 0.05 SOL per token)
const maxPrice = encodeQ96("0.05");

// Amount of quote currency to bid (in atomic units, e.g., 1_000_000 = 1 USDC)
const amount = BigInt(1_000_000);

// Ensure the bidder's quote token ATA exists
const bidderQuoteAccount = getAssociatedTokenAddress(
  quoteMint,
  wallet.publicKey
);
const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
  wallet.publicKey,
  bidderQuoteAccount,
  wallet.publicKey,
  quoteMint
);

const placeBidIx = buildPlaceBidInstruction({
  bidder: wallet.publicKey,
  auctionConfig,
  maxPrice,
  amount,
  prevTickPrice: BigInt(0), // 0 if no previous tick in the linked list
  totalBids: BigInt(auction.total_bids), // current bid count from auction state
  latestCheckpointAuctionBlock: BigInt(
    auction.latest_checkpoint_auction_block
  ),
  bidderQuoteAccount,
  tokenProgram: TOKEN_PROGRAM_ID,
});

const tx = new Transaction().add(createAtaIx, placeBidIx);
const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);

console.log("Bid placed:", signature);
caution

Read total_bids and latest_checkpoint_auction_block from the indexer (or on-chain auction state) immediately before building the transaction. Stale values will cause the bid PDA derivation to fail.

Check Bid Status​

After placing a bid, query the indexer to see its current state:

// Find your bids by wallet address
const bidsResponse = await fetch(
  `${INDEXER_URL}/api/bidder/${wallet.publicKey.toBase58()}/bids`
);
const { data: bids } = await bidsResponse.json();

for (const bid of bids) {
  console.log(`Bid ${bid.pubkey}:`);
  console.log(`  Max price: ${bid.max_price}`);
  console.log(`  Amount: ${bid.raw_amount}`);
  console.log(`  Eligible: ${bid.is_eligible}`);
  console.log(`  Tokens filled: ${bid.tokens_filled}`);
}

Next Steps​

  • Architecture Overview -- understand how the Launchpad, CCA V2, and indexer fit together
  • SDK Reference -- full API reference for PDA derivation, instruction builders, and Q96 math
  • Indexer API -- complete endpoint documentation for the REST and WebSocket APIs