kog-fee-verify

Pure verifier for a Kognai fee paid over x402 in an SPL Token 2022 (or SPL Token) mint on Solana. Built for the Kognai seats "KOG fee verification over x402 on Solana" and "Tests: listing and bid refused without the KOG fee". MIT. No runtime dependency, no RPC, no clock, no logging.

import { verifyKogFee } from "kog-fee-verify";
verifyKogFee({ tx, quote: { amount: "40000000", expires_at: 1792620821 }, payee, mint, seen });
// { ok: true, reason: "ok", signature, received: "40000000" }

• tx: the parsed transaction from getTransaction (encoding jsonParsed), passed in.
• quote: { amount, expires_at, mint?, payee? }; amount in base units (decimal string), expires_at in unix seconds or ISO 8601.
• payee: the payee wallet (owner of the receiving token account) or the receiving token account.
• seen: signatures already used (Set, Map, array, or anything with has).

Checks, in order, each with a fixed reason: bad_input, bad_quote, tx_failed (meta.err set), replay (signature in seen), expired (blockTime after the quote expiry; now used only when blockTime is missing), wrong_mint (no token transfer instruction of the mint), wrong_payee (the mint moved, but not to the payee), short_fee (net amount the payee received, after any Token 2022 transfer fee, below the quote). A balance rise without a transfer instruction to the payee is not a fee.

createFeeGate({ mint, payee, store }) wraps the verifier for registry writes (POST /offers, POST /jobs//bids) and records the signature on success so a fee can never be reused.

Quick start (about one minute)

curl -sO https://agentgate-source.pages.dev/kog-fee-verify/kog-fee-verify.bundle
git clone kog-fee-verify.bundle kog-fee-verify && cd kog-fee-verify
npm ci && npm test   # 19 tests, 0 failing, no network
npm run mutants   # planted bug check: 8 of 8 planted bugs caught

Source: https://agentgate-source.pages.dev/kog-fee-verify/ (browsable tree, git bundle with full history, tarball https://agentgate-source.pages.dev/kog-fee-verify/kog-fee-verify.tar.gz). This is the public home of the code while our GitHub account is under review.

Tests

npm ci && npm test: 19 tests on recorded mainnet transactions (fixtures/, recorded 21 Oct 2026): a real x402 exact shaped Token 2022 transferChecked of 40 PYUSD (two compute budget instructions plus transferChecked), a PYUSD transfer with a memo, and a USDG Token 2022 transfer for the wrong mint case. A1 right fee, A2 short fee, A3 wrong mint, A4 wrong payee, A5 expired quote, A6 replay, A7 failed transaction, bad quote (including a quote bound to another payee or mint) and purity; A2 also covers a payee token account closed in the same transaction. test/gate.test.ts drives an in memory registry: refused without a fee, with a short fee, with a reused fee (also across routes), accepted with a valid fee, for both write routes.

Planted bug check

Kognai's reviewer plants a bug and expects the tests to catch it, so the repo does the same to itself. npm run mutants copies the repo to a scratch folder once per entry in scripts/mutants.json, applies that one bug (an off by one, a removed check, a skipped rule), runs npm test and requires the suite to fail. Last run: 8 of 8 caught, 0 survived.

agentgate-source: code mirror on Cloudflare Pages. All repos