Automation#

Automated trading on Seesaw means reading on-chain state, applying strategy logic, and submitting signed instructions programmatically — without a UI.

This page covers two related topics:

1. Permissionless lifecycle cranks — anyone can run the market lifecycle (create, snapshot, resolve, expire) and earn SOL rewards for doing so.
2. Automated trading bots — placing and cancelling orders, managing inventory, and handling settlement automatically.

Permissionless cranks#

Seesaw has no privileged keeper or operator. Every lifecycle step is a public instruction that anyone can call. Native markets use an off-chain cranker to fetch a signed Pyth update, post it through the pinned Pyth Receiver, and pass the resulting account into Seesaw. The protocol rewards timely execution with lamport payments:

Crank rewards#

Each successful lifecycle instruction earns a SOL reward paid directly from the market account:

The default reward is DEFAULT_CLOSER_REWARD_LAMPORTS = 200,000 lamports (0.0002 SOL). Each market pre-funds up to 5 reward payouts at creation. The reward is admin-tunable (via UpdateOperationalParams 0x2F) but only for future markets — existing markets are funded at the rate in effect when they were created.

Duplicate calls (e.g., two cranks racing to snapshot the same market) are safe — all lifecycle instructions are idempotent. The first successful call earns the reward; subsequent calls are no-ops and earn nothing.

ExpireMarket: three-tier fallback#

ExpireMarket is only available after t_end + market_expiration_window (default 7 days from the spec — see MARKET_EXPIRY_WINDOW = 604800 s in program/src/constants.rs). It tries to resolve normally before falling back:

Tiers 1 and 2 mean users rarely get the 50/50 penalty — the expire crank first tries every reasonable path to a normal outcome.

Minimal crank loop#

use solana_client::rpc_client::RpcClient;

async fn crank_loop(rpc: &RpcClient, program_id: Pubkey, duration_seconds: u64) {
    loop {
        let clock = rpc.get_clock().unwrap();
        let now = clock.unix_timestamp as u64;

        // Look back far enough to catch unresolved markets — cover the
        // full 7-day expiration grace window (604,800 s).
        let lookback = 604_800 / duration_seconds;
        let current_epoch = now / duration_seconds;

        for offset in 0..=lookback {
            let market_id = current_epoch.saturating_sub(offset);
            let t_start = market_id * duration_seconds;
            let t_end = t_start + duration_seconds;

            let market_pda = derive_market_pda(market_id, &program_id);

            match rpc.get_account(&market_pda) {
                Err(_) => {
                    // Market doesn't exist yet
                    if now >= t_start {
                        send_create_market(market_id).await;
                    }
                }
                Ok(account) => {
                    let market = MarketAccount::deserialize(&account.data).unwrap();
                    if market.outcome == 0
                        && market.end_price == 0
                        && now >= t_end + (7 * 24 * 3600)  // MARKET_EXPIRY_WINDOW
                    {
                        // For Pull markets, this still needs a Receiver-owned
                        // PriceUpdateV2 account for the market feed.
                        send_expire_market(market_id).await;
                    } else if market.end_price == 0 && now >= t_end {
                        send_snapshot_end(market_id).await;
                    } else if market.outcome == 0 && market.end_price != 0 {
                        send_resolve_market(market_id).await;
                    }
                }
            }
        }

        tokio::time::sleep(Duration::from_secs(1)).await;
    }
}

Note: redeem is not a crank operation. Traders trigger their own Redeem — this is by design so that payouts go to the position owner, not to whoever happens to run a crank.

Pull-oracle markets#

For native markets, the SnapshotEnd crank requires an additional step: fetching the exact first post-boundary price from Pyth's Hermes API and posting it on-chain as a PriceUpdateV2 account. The SDK's resolveSnapshotEnd helper bundles this automatically.

Pull makes Sampling Rule A firstness deterministic — Hermes can serve the exact first post-boundary print before the crank submits the lifecycle instruction.

Seesaw's default Pull keeper is open source in services/pyth-keeper, and a public operator guide is available at Run A Pyth Pull Keeper. It is not privileged: any caller with a funded Solana fee payer and a valid Pyth update account can submit the same snapshot_end, resolve_market, or expire_market instructions. Production operators should monitor both the keeper process and indexed market state; a running process alone does not prove markets are advancing.

Automated trading bots#

Architecture overview#

Reading market state#

Use WebSocket subscriptions (accountSubscribe) for latency-sensitive strategies. Use polling as a fallback or for lower-frequency strategies.

Free-funds trading#

For high-frequency strategies, use the *WithFreeFunds instruction variants. These operate on an internal trader-ledger balance instead of performing SPL token transfers on every order:

DepositFunds      → deposit stablecoin into quote_free (your ledger balance)
SwapWithFreeFunds → IOC order settled against ledger (no per-order token CPI)
PlaceLimitOrderWithFreeFunds → Limit/PostOnly settled against ledger
CancelMultipleOrdersByIdWithFreeFunds → cancel + refund to ledger
WithdrawFunds     → withdraw quote_free back to your wallet

Free-funds orders reduce transaction cost and latency for bots that cycle rapidly through the same capital.

Order lifecycle state tracking#

Order states:
  Active          → resting on the book, waiting to fill
  PartiallyFilled → some quantity matched, remainder resting
  Filled          → fully matched, slot can be freed
  Cancelled       → you cancelled it
  ExpiredClaimable → TTL elapsed; permissionless ReclaimExpiredOrder available

Track your orders by order_id. After each transaction, re-read the orderbook PDA to confirm actual state.

Pre-trade checks#

Always validate before sending:

Retry and error handling#

Settlement automation#

Bots should automate the claim step too, not just order placement:

Critical: automate claims or you risk the 7-day forfeiture window. A bot that places orders but doesn't claim is leaving money behind. See Claiming Winnings and Risks.

Strategy patterns#

Momentum#

Track Pyth oracle price movements and trade in the direction of recent momentum:

Market making#

See Market Making for the full two-sided quoting strategy. The key loop for a maker bot:

1. Read book → compute mid → compute bid/ask
2. Cancel stale quotes
3. Place new quotes via PlaceMultiplePostOnlyOrders
4. Monitor fills → adjust inventory skew
5. Cancel all before t_end − safety_margin

Arbitrage#

When YES + NO < 10000 bps (both available cheaper than $1 total): buying both locks in a guaranteed profit at settlement. Always net against the taker fee before acting.

Priority fees#

During network congestion, add compute-budget priority fees:

Also prepend RequestHeapFrame(64 KiB) for PlaceOrder on a full book — the place-order hot path can exceed Solana's default 32 KiB heap.

Operational considerations#

Key management#

Uptime#

The Seesaw protocol operates continuously. Market lifecycles run 24/7 via permissionless cranks. Your bot should handle:

• RPC node downtime → failover endpoint
• Websocket disconnects → reconnect with state re-sync
• Program errors → circuit breaker to pause and alert

Testing#

1. Devnet first. Run your strategy with devnet USDT before mainnet.
2. Paper trading. Log intended orders without sending them to verify logic.
3. Small capital. Ramp up gradually: 1% → 10% → full capital.

Next steps#

• Market Making — the two-sided quoting strategy in detail
• Placing Orders — all order types, free-funds variants, TTL
• Risks — admin controls (pause/post-only) that affect bots
• SDK Guide — TypeScript, Python, and Rust SDK references

Technical reference#