Programs

SPL Token transfers: Transfer and TransferChecked

Two instructions carry almost every plain token transfer: Transfer and TransferChecked. Both fit in a few bytes, and one of them leaves out the mint. This page decodes both from the instruction alone and shows exactly when you still need an account lookup.

To decode an SPL Token transfer, match instructions whose program is TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA, then read the first byte. Tag 3 is Transfer: an 8-byte little-endian amount. Tag 12 is TransferChecked: the same amount plus one byte of decimals, and it names the mint. A plain Transfer needs one lookup to learn its mint.

Program ID and instruction tags#

The program ID is TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA. Token-2022 is a different program with its own ID and extensions; it has its own recipe.

TagInstructionData after the tagAccounts, in order
3Transferamount: u64, little-endiansource, destination, authority
12TransferCheckedamount: u64, then decimals: u8source, mint, destination, authority

Amounts are in the token's smallest unit: move the decimal point left by the mint's decimals to show a human amount. When the authority is a multisig, its signers follow as extra accounts; the first three or four positions stay the same. The program reads only the bytes it needs and ignores anything after them, so the decoder checks for a minimum length, not an exact one.

Steps#

  1. Keep only instructions whose program, looked up through the static keys, is the SPL Token program. The program filter does this before any of the steps below run.
  2. Read the tag byte. Ignore everything except 3 and 12.
  3. Read the amount as a u64 at offset 1, and for TransferChecked the decimals at offset 9.
  4. Map the accounts by position: source, destination and authority, plus the mint for TransferChecked. In a v0 transaction an account index may point into a lookup table, so resolve the tables before you read names.
  5. For a plain Transfer, find the mint and decimals from the source token account.

token.ts#

Instruction comes from view.ts on the filtering page, which turns legacy, v0 and v1 transactions into one shape.

TypeScript
// D13: SPL Token Transfer (tag 3) and TransferChecked (tag 12) from instruction bytes.
// Layout: solana-program/token interface/src/instruction.rs (u8 tag, then u64 LE amount; Checked adds u8 decimals).
import type { Instruction } from "./view.ts";
export const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
export type TokenTransfer = {
kind: "transfer" | "transferChecked";
source: string; destination: string; authority: string;
amount: bigint;
mint?: string; // only TransferChecked names the mint
decimals?: number; // only TransferChecked carries decimals
};
/** Decode one top-level SPL Token instruction. Returns null for every other instruction. */
export function decodeTokenTransfer(ix: Instruction, keys: string[]): TokenTransfer | null {
if (keys[ix.programIndex] !== TOKEN_PROGRAM) return null;
const d = ix.data, v = new DataView(d.buffer, d.byteOffset, d.byteLength);
const acct = (i: number) => keys[ix.accounts[i]];
if (d[0] === 3 && d.length >= 9) { // the program reads 8 amount bytes and ignores anything after
// accounts: source, destination, authority
return { kind: "transfer", source: acct(0), destination: acct(1), authority: acct(2), amount: v.getBigUint64(1, true) };
}
if (d[0] === 12 && d.length >= 10) {
// accounts: source, mint, destination, authority
return { kind: "transferChecked", source: acct(0), mint: acct(1), destination: acct(2), authority: acct(3), amount: v.getBigUint64(1, true), decimals: d[9] };
}
return null;
}
/**
* A plain Transfer names neither the mint nor its decimals. Look them up from the source token account
* (getAccountInfo on it, or your own cache of token accounts), then fill them in.
*/
export function withMint(t: TokenTransfer, mintOf: (tokenAccount: string) => { mint: string; decimals: number } | undefined): TokenTransfer {
if (t.mint) return t;
const m = mintOf(t.source);
return m ? { ...t, mint: m.mint, decimals: m.decimals } : t;
}

Finding the mint for a plain Transfer#

TransferChecked names the mint, so it decodes completely from its own bytes. Transfer does not: its accounts are only the two token accounts and the authority. The mint is stored inside the source token account, so read that account once with getAccountInfo, or keep a cache of token accounts you have already seen, and pass the result to withMint.

A cache works well because token accounts rarely change mint: the field is fixed when the account is created. Expect a miss the first time you see an account, and decide whether to wait for the lookup or emit the transfer with the mint marked unknown.

How this was tested#

The test set is the shared pair of mainnet blocks used across these docs, plus a handful of SPL Token sample transactions, each kept with the meta RPC returned for it. Every successful transfer was checked against what the chain recorded: the destination's token balance change, its mint and its decimals. Tests: node test-recipes.ts on Node 24.14 with @solana/kit 8.6.0.

InstructionMatched the chainMismatchesNot checkable from balances alone
Transfer, with the mint looked up from the source account600
TransferChecked7016

"Not checkable" means another instruction in the same transaction, or an inner call, also moved tokens in or out of that destination, so its balance change is not this transfer alone. Those transfers decoded without error; they just cannot be checked against balances by themselves.

Token moves you will not see: calls made by other programs#

Most token movement on Solana happens inside other programs: a swap, a lending action or a launchpad buy calls the token program for you. Those calls are inner instructions. They run when the transaction executes, and shreds carry only the instructions the user signed, so a decoder working from shreds never sees them. Inner instructions and CPI explains this in full.

What you decode here is what the transaction asked for, not what happened. A transfer can fail, for example on an insufficient balance, and the bytes look identical either way. Treat every decoded transfer as provisional until the transaction is confirmed.

Questions#

What is the difference between Transfer and TransferChecked?#

TransferChecked also names the mint and states the decimals, and the program refuses the transfer if they do not match. That makes it safer for wallets, and for decoders it means the transfer is complete from its own bytes.

Why is the amount so large?#

It is in the token's smallest unit. A token with 6 decimals stores 1.5 tokens as 1,500,000, so move the decimal point six places left to display it.

Does this decode Token-2022 transfers?#

No. Token-2022 is a separate program with its own ID and extensions such as transfer fees, which change what a transfer moves. Use the Token-2022 recipe for it.

Next#

The SPL Token instructions you will decode most covers the rest of the program, and SOL transfers is the same recipe for the System program. To alert on transfers without crying wolf, read wallet alerts without false alarms. To run it on 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.