Token-2022 recipe: transfers and extensions
A Token-2022 transfer can deliver less than it sends, and the instruction alone does not always say how much less. This recipe decodes all three transfer forms, reads the mint state that decides the rest, and was checked against the recipient balances of real mainnet transfers, fee-bearing ones included.
To decode a Token-2022 transfer, read its tag: 3 is Transfer, 12 is TransferChecked, and 26 followed by 1 is TransferCheckedWithFee. All three name the amount taken from the source. Only the last also states the fee. For the others, what the recipient gets depends on the mint's transfer fee settings, which you must read from the mint account.
Program IDs and sources#
| What | Value |
|---|---|
| Token-2022 program ID | TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb |
| SPL Token program ID | TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA |
| Layouts | solana-program/token-2022, commit 875693f |
| Runtime | Node 24, no dependencies |
Token-2022 is not an Anchor program: it has no IDL and no discriminators, just a one-byte tag like the classic program. Both appear with their sources on the program IDs page. The classic program now runs p-token, which added new tags of its own, including a Batch instruction (255); that change applies to SPL Token only, not to Token-2022.
Three transfer forms and what the recipient gets#
| Form | Data after the tag | Accounts | Recipient receives |
|---|---|---|---|
| Transfer (3) | amount (u64) | source, destination, authority | the amount; Token-2022 refuses it when the source account carries fee, hook or pause state |
| TransferChecked (12) | amount (u64), decimals (u8) | source, mint, destination, authority | the amount, less the mint's transfer fee if it has one |
| TransferCheckedWithFee (26, 1) | amount (u64), decimals (u8), fee (u64) | source, mint, destination, authority | the amount less the stated fee; the program rejects it if the fee is not the one it computes |
So the form that tells you everything is the rarest. We found no TransferCheckedWithFee among the transfers in our samples, so our code decodes it from the layout but it is untested on real data. The everyday form on fee-bearing mints is TransferChecked, and there the fee is not in the instruction at all. The extension side of Token-2022 is covered in Token-2022 extensions; this page is about reading the transfers.
How the transfer fee is computed#
A mint with the transfer fee extension stores two fee settings, an older and a newer, each with a starting epoch, a rate in basis points and a maximum. The program uses the newer one once the current epoch reaches its starting epoch, and the older one before that. The fee is the amount times the rate divided by 10,000, rounded up, and never more than the maximum.
Rounding up is visible on chain. On a 3 percent mint, a TransferChecked of 15,000,859,137,060 raw units gives 450,025,774,111.8 before rounding; the recipient received 14,550,833,362,948, exactly 450,025,774,112 less. On a 0.5 percent mint, an inner transfer of 1,678,664 gives 8,393.32; 8,394 was withheld.
The epoch matters because a mint's owner can schedule a new rate. To know which setting applied, compute the epoch from the slot: on mainnet each epoch is 432,000 slots, so slot 448,575,076 is in epoch 1,038.
Extensions that need mint state#
| Extension | What it changes | Can you read it from the transfer? |
|---|---|---|
| Transfer fee | what the recipient receives | only with TransferCheckedWithFee; otherwise read the mint |
| Scaled UI amount | the displayed amount: raw units times a multiplier, which can change at a set time | no: the raw amount is unchanged, the display depends on the mint |
| Interest-bearing | the displayed amount grows over time | no |
| Transfer hook | another program runs on every transfer and adds accounts to the instruction | partly: the extra accounts appear, their meaning comes from the hook program |
| Pausable, default account state, non-transferable | whether a transfer can happen at all | no: read the mint and the accounts |
| Permanent delegate | who may sign a transfer | no |
Among the 154 Token-2022 mints in our fixtures, 7 had the transfer fee extension (one of them set to 0 basis points), 7 had a scaled UI amount and 10 had a transfer hook. Most mints carry only metadata extensions, which change nothing about transfers. Token-2022 surprises collects the cases that catch decoders out.
Steps#
- For each top-level call to either token program, decode it with
decodeTokenTransfer. It returnsnullfor anything that is not one of the three transfer forms. - Keep a cache of mint state. Fetch each new Token-2022 mint once with
getAccountInfoin base64 and parse it withreadMint; refresh when the mint changes, since fee settings and multipliers can be updated. - Call
amountReceivedwith the slot's epoch to get what lands in the destination. - Plain Transfer names no mint. If you need the mint, take it from the destination account's own data, or from the balance records RPC returns after execution.
- After confirmation, compare with the balance change from RPC. Our tests matched it on every transfer they could isolate.
src/token2022.ts#
// Token-2022 transfers, and the mint state needed to know what the recipient actually receives.// Layouts: solana-program/token-2022 interface (instruction.rs, extension/mod.rs ExtensionType order,// extension/transfer_fee/mod.rs, extension/scaled_ui_amount/mod.rs), commit 875693f. SPL Token shares tags 3 and 12.import { b58 } from "./base58.ts";export const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";export const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";export type TokenTransfer = {program: string; kind: "transfer" | "transferChecked" | "transferCheckedWithFee";source: string; mint: string | null; destination: string; authority: string;amount: bigint; // taken from the sourcedecimals: number | null; // checked variants onlydeclaredFee: bigint | null; // transferCheckedWithFee only; the program rejects it unless it equals the mint's fee};/** Top-level Transfer (3), TransferChecked (12) and, for Token-2022, TransferCheckedWithFee (26, 1). */export function decodeTokenTransfer(programId: string, data: Uint8Array, accounts: string[]): TokenTransfer | null {if (programId !== TOKEN_PROGRAM && programId !== TOKEN_2022_PROGRAM) return null;const v = new DataView(data.buffer, data.byteOffset, data.byteLength);const base = { program: programId, declaredFee: null };if (data[0] === 3 && data.length === 9)return { ...base, kind: "transfer", source: accounts[0], mint: null, destination: accounts[1], authority: accounts[2], amount: v.getBigUint64(1, true), decimals: null };if (data[0] === 12 && data.length === 10)return { ...base, kind: "transferChecked", source: accounts[0], mint: accounts[1], destination: accounts[2], authority: accounts[3], amount: v.getBigUint64(1, true), decimals: data[9] };if (programId === TOKEN_2022_PROGRAM && data[0] === 26 && data[1] === 1 && data.length === 19)return { ...base, kind: "transferCheckedWithFee", source: accounts[0], mint: accounts[1], destination: accounts[2], authority: accounts[3],amount: v.getBigUint64(2, true), decimals: data[10], declaredFee: v.getBigUint64(11, true) };return null;}// ExtensionType values are the enum's order in extension/mod.rs.const EXT = ["Uninitialized", "TransferFeeConfig", "TransferFeeAmount", "MintCloseAuthority", "ConfidentialTransferMint","ConfidentialTransferAccount", "DefaultAccountState", "ImmutableOwner", "MemoTransfer", "NonTransferable", "InterestBearingConfig","CpiGuard", "PermanentDelegate", "NonTransferableAccount", "TransferHook", "TransferHookAccount", "ConfidentialTransferFeeConfig","ConfidentialTransferFeeAmount", "MetadataPointer", "TokenMetadata", "GroupPointer", "TokenGroup", "GroupMemberPointer","TokenGroupMember", "ConfidentialMintBurn", "ScaledUiAmount", "Pausable", "PausableAccount", "PermissionedBurn"];type Fee = { epoch: bigint; maximumFee: bigint; basisPoints: number };export type MintState = {decimals: number; extensions: string[];transferFee: { older: Fee; newer: Fee } | null;scaledUiAmount: { multiplier: number; newMultiplier: number; newMultiplierTimestamp: bigint } | null;transferHookProgram: string | null;};/** Parse a mint account's raw data (base mint, then account type at byte 165, then type-length-value extensions). */export function readMint(data: Uint8Array): MintState {const v = new DataView(data.buffer, data.byteOffset, data.byteLength);const st: MintState = { decimals: data[44], extensions: [], transferFee: null, scaledUiAmount: null, transferHookProgram: null };if (data.length <= 165 || data[165] !== 1) return st; // a plain mint: no extensionsfor (let o = 166; o + 4 <= data.length;) {const type = v.getUint16(o, true), len = v.getUint16(o + 2, true), b = o + 4;if (type === 0 && len === 0) break;st.extensions.push(EXT[type] ?? `extension ${type}`);const fee = (p: number): Fee => ({ epoch: v.getBigUint64(p, true), maximumFee: v.getBigUint64(p + 8, true), basisPoints: v.getUint16(p + 16, true) });if (type === 1) st.transferFee = { older: fee(b + 72), newer: fee(b + 90) }; // two authorities (32 each), withheld u64if (type === 25) st.scaledUiAmount = { multiplier: v.getFloat64(b + 32, true), newMultiplierTimestamp: v.getBigInt64(b + 40, true), newMultiplier: v.getFloat64(b + 48, true) };if (type === 14) { const p = b58(data.subarray(b + 32, b + 64)); st.transferHookProgram = p === "11111111111111111111111111111111" ? null : p; }o = b + len;}return st;}/** The fee the program withholds from a transfer in `epoch`: ceil(amount x bps / 10,000), capped at the maximum. */export function transferFee(mint: MintState, amount: bigint, epoch: bigint): bigint {if (!mint.transferFee) return 0n;const f = epoch >= mint.transferFee.newer.epoch ? mint.transferFee.newer : mint.transferFee.older;const raw = (amount * BigInt(f.basisPoints) + 9_999n) / 10_000n;return raw < f.maximumFee ? raw : f.maximumFee;}/** What lands in the destination account. Needs mint state for every variant except transferCheckedWithFee. */export function amountReceived(t: TokenTransfer, mint: MintState | null, epoch: bigint): bigint {if (t.kind === "transferCheckedWithFee") return t.amount - t.declaredFee!;if (t.program === TOKEN_PROGRAM || !mint) return t.amount;return t.amount - transferFee(mint, t.amount, epoch);}
Real transfers on a fee-bearing mint#
| Field | Transfer, slot 448,575,076 | Transfer, slot 470,917,488 |
|---|---|---|
| form | TransferChecked, top level | TransferChecked, top level |
| mint | DdvgbCH2N2Yo9fgCq8yb2qqNYDFJtsr1GT2pRVhJxsXi | VzUPBWqREGVggS27kiFuSVZFUVFt1f9VrMfecjT8888 |
| mint fee setting | 300 basis points, maximum 1,000,000,000,000,000, from epoch 1,038 | 300 basis points, maximum 1,000,000,000,000,000,000, from epoch 1,009 |
| amount in the instruction | 15,000,859,137,060 | 100,000,000,000 |
fee computed by transferFee | 450,025,774,112 | 3,000,000,000 |
| recipient's balance change, from RPC | 14,550,833,362,948 | 97,000,000,000 |
Neither instruction mentions a fee. Without the mint state, a decoder would record the recipient as receiving 3 percent more than arrived.
How this code was tested#
| Check | Result |
|---|---|
readMint against RPC's parsed view: extensions, decimals, fee settings, scale multipliers | 154/154 mints |
| Token-2022 TransferChecked, no fee, recipient's balance change | 15/15 top level, 358/358 inner |
| Token-2022 TransferChecked, fee withheld | 2/2 top level, 3/3 inner |
| SPL Token Transfer and TransferChecked | 6/6 and 21/21 top level, 31/31 and 366/366 inner |
| Token-2022 TransferCheckedWithFee | none found: decoded from the layout, untested on real data |
A transfer counts only when no other token instruction in the transaction touches its destination, so the balance change is that transfer's alone. Inner transfers, made by other programs, are not in shreds, but they run through the same fee rule and were included to test it on more than two transfers. Mint state was read on 18 November 2026 and fees use each transfer's own epoch. On every fee mint in our samples the older and newer settings were identical, so the choice between them follows the source but was not exercised by these tests. The test is test-token2022.ts in the examples' test-all.sh.
What the instruction cannot tell you#
For TransferChecked on a fee-bearing mint, the instruction gives the amount sent, not the amount received; you need the mint. Displayed amounts on scaled and interest-bearing mints need mint state and a time. Transfer-hook programs can make a transfer fail for their own reasons. Plain Transfer does not name the mint. Transfers made by other programs, which is most transfers in DEX swaps, are inner instructions and do not appear in shreds. And this decoder does not unpack SPL Token's Batch instruction.
More about tokens#
The instruction tags of the classic token program are listed separately, and associated token accounts explains how token accounts relate to wallets. The Raydium CPMM and CLMM recipe shows a pool deposit that lost 3 percent to a transfer fee. To decode token transfers as blocks are produced, see the plans.
Sources#
- solana-program/token-2022 commit 875693f: interface instruction.rs (TransferChecked 12, TransferFeeExtension 26 sub-instruction 1), extension/mod.rs ExtensionType order (checked 2026-11-18)
- solana-program/token-2022 875693f extension/transfer_fee/mod.rs: ceiling division, maximum fee, older and newer fee chosen by epoch (checked 2026-11-18)
- solana-program/token-2022 875693f program/src/processor.rs process_transfer: MintRequiredForTransfer for fee, hook and pausable accounts; FeeMismatch (checked 2026-11-18)
- solana-program/token-2022 875693f extension/scaled_ui_amount/mod.rs: multiplier and new multiplier with an effective time (checked 2026-11-18)
- solana-program/token-2022 875693f extension/interest_bearing_mint/mod.rs: rate-based UI amount over time (checked 2026-11-18)
- Mainnet getMultipleAccounts (base64 and jsonParsed) for the 154 Token-2022 mints in our fixtures, slot 470,947,841 (checked 2026-11-18)
- Fee-withheld transfers jeuY5dMSVN9uNRYLMVp5pUXEL3mDgpcdfeZHSD4PhkCsUx963wuq5vm36GDfbdsHJvaXCWJGmEDzoEkf5rgS95G (slot 448,575,076) and 3PdqjT9961fBu1yCS6fMEadqeZGeeiRWAXMbvRQYzS7FTbg5aKiErNPrwTYUqGbmPJh5rXHzNp5hXudLgZYAycq5 (slot 470,917,488) (checked 2026-11-18)
- Examples test-token2022.ts on transactions fetched from public mainnet RPC on 2026-11-18 (checked 2026-11-18)
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.