Programs

Detecting SOL transfers with the System program

A deposit watcher for SOL that reads System program instructions straight from the stream and marks every deposit it finds as provisional. You see the transfer as the block forms; you credit it only once the chain confirms it.

To detect incoming SOL before confirmation, watch System program instructions whose 4-byte tag is 2 (Transfer) or 11 (TransferWithSeed), read the u64 lamport amount after the tag, and compare the destination account with your watchlist. Record each hit as provisional: the transaction can still fail, so credit the deposit only after it is confirmed.

Program ID and the transfer instruction layout#

The System program ID is 11111111111111111111111111111111. Its instructions start with a 4-byte little-endian tag, not the single byte the token program uses.

TagInstructionData after the tagAccounts, in order
2Transferlamports: u64, little-endiansource, destination
11TransferWithSeedlamports: u64, then the seed and its owner programsource (derived), base, destination

One SOL is 1,000,000,000 lamports. In both instructions the amount sits at the same offset, right after the tag, which keeps the decoder short.

Steps#

  1. Keep instructions whose program, looked up through the static keys, is the System program. The program filter does this cheaply.
  2. Read the 4-byte tag and keep 2 and 11.
  3. Read the lamports as a u64 at offset 4.
  4. Take the destination: the second account for Transfer, the third for TransferWithSeed. In a v0 transaction resolve lookup tables first, in case the destination was loaded from one.
  5. If the destination is on your watchlist, emit a deposit marked provisional, with the slot and signature.
  6. Confirm it before you credit anything: check the signature's status, and follow reconciling with confirmed data for what to do when a transaction never confirms.

sol.ts#

Instruction and TxView come from view.ts on the filtering page.

TypeScript
// D14: detect SOL sent to watched addresses from System program instructions, and report each one as provisional.
// Layout: solana-program/system (u32 LE tag; Transfer = 2 with u64 lamports; TransferWithSeed = 11 with u64 lamports first).
import type { Instruction, TxView } from "./view.ts";
export const SYSTEM_PROGRAM = "11111111111111111111111111111111";
export type SolTransfer = { from: string; to: string; lamports: bigint };
/** Decode a top-level System Transfer or TransferWithSeed. Returns null for every other instruction. */
export function decodeSolTransfer(ix: Instruction, keys: string[]): SolTransfer | null {
if (keys[ix.programIndex] !== SYSTEM_PROGRAM || ix.data.length < 12) return null;
const v = new DataView(ix.data.buffer, ix.data.byteOffset, ix.data.byteLength);
const tag = v.getUint32(0, true), lamports = v.getBigUint64(4, true);
const acct = (i: number) => keys[ix.accounts[i]];
if (tag === 2) return { from: acct(0), to: acct(1), lamports }; // accounts: from, to
if (tag === 11) return { from: acct(0), to: acct(2), lamports }; // accounts: from, base, to
return null;
}
export type Deposit = SolTransfer & { slot: number; signature: string; status: "provisional" };
/**
* Deposits to watched addresses, straight from shreds. Every one is provisional: the transaction may still fail or
* never be confirmed, so credit it only after you confirm it (getSignatureStatuses, or the confirmed block).
*/
export function depositsIn(v: TxView, slot: number, keys: string[], watch: Set<string>): Deposit[] {
const out: Deposit[] = [];
for (const ix of v.instructions) {
const t = decodeSolTransfer(ix, keys);
if (t && watch.has(t.to)) out.push({ ...t, slot, signature: v.signature, status: "provisional" });
}
return out;
}

TransferWithSeed and nonce cases#

TransferWithSeed moves lamports out of an account whose address is derived from a base key and a seed, so the source is not a normal signer. For a deposit watcher only the destination and the amount matter, and both decode the same way as a plain Transfer, with the destination one position later.

Durable nonce transactions carry a nonce instead of a recent blockhash and can be submitted long after they were signed. They often start with an AdvanceNonceAccount instruction, also from the System program, which this decoder ignores because it moves no SOL. The transfer in the same transaction still decodes normally. Expect such transactions to land late, and do not use the blockhash age to judge them; durable nonce transactions explains why.

How this was tested#

Each successful transfer was checked against the lamport balance change the chain recorded for its recipient. The inputs were our two shared mainnet blocks and a set of System sample transactions, each with its RPC meta. Tests: node test-recipes.ts on Node 24.14 with @solana/kit 8.6.0.

CheckMatched the chainMismatchesNot checkable from balances alone
Transfer amount against the recipient's balance change780147
Watcher: one provisional deposit per decoded transfer to a watched address220 transactions00

"Not checkable" covers recipients whose balance also moved for another reason in the same transaction: a second transfer, an inner call, or the fee payer receiving funds. The transfers themselves decoded without error.

Transfers inside CPIs are not visible#

SOL that another program sends on a user's behalf, for example a payout from a game or a protocol's withdrawal, moves through an inner call to the System program. Shreds carry only the instructions the user signed, so this watcher cannot see those deposits. If you must catch every incoming lamport, add a confirmed-data source for the address, such as getSignaturesForAddress after confirmation.

The watcher also cannot tell whether a transfer succeeded. A transfer from an account without enough SOL looks the same in the stream as one that works, which is the whole reason the status starts as provisional. Landed but failed covers transactions that reach a block yet do nothing.

Questions#

How do I detect incoming SOL before confirmation?#

Decode System Transfer and TransferWithSeed instructions from the stream and match their destination against your addresses. You see the deposit while the block is still forming, but it is only a promise until the transaction confirms.

Why not credit the deposit straight away?#

Because a transaction in the stream may still fail or end up in a block that does not survive. Show it as pending, and credit it once its status is confirmed.

Does this catch SOL sent by a program?#

No. A program that pays out SOL does so through an inner call, which shreds do not carry. Use a confirmed source for those.

Next#

Provisional rows is about storing what you saw before the chain agreed, and token transfers is the same recipe for SPL tokens. Spotting new accounts builds on System instructions too. To watch a live stream, see pricing.

Sources#

Raw shreds on your own server

Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.