---
title: "Token-2022 Transfer-Fee Payment Reconciler"
method: POST
path: "/v1/tools/reconcile_token2022_transfer_fee"
tags: ["token2022", "solana", "transfer-fee", "payment-reconciliation", "fee-withholding", "kora", "x402", "svm", "bigint", "mcp:reconcile_token2022_transfer_fee"]
---

# Token-2022 Transfer-Fee Payment Reconciler

`POST /v1/tools/reconcile_token2022_transfer_fee`

## Request

- Base URL: `https://ainumbers.co`
- URL: `https://ainumbers.co/v1/tools/reconcile_token2022_transfer_fee`
- Auth: none declared

Recomputes the transfer fee a Token-2022 mint with the transfer-fee extension withholds and the net amount the recipient receives, given the fee schedule, the TransferChecked amount, the execution epoch and the amount a payment verifier credited, then reconciles the credited amount against that net: MATCH, OVER_CREDITED (the Kora GHSA-725g defect class, a verifier crediting the pre-fee amount) or UNDER_CREDITED, with credited_minus_net reported. All amounts are decimal strings computed in BigInt (128-bit intermediates, no floats). The output also records a declared-fee FeeMismatch for TransferCheckedWithFee, an epoch-schedule divergence when the verifier used a different schedule than the execution epoch, and an informational consumer view showing where the x402 SVM gross-amount path and the balance-delta net path disagree.

**Tool URL:** https://ainumbers.co/chaingraph/art-715-token2022-transfer-fee-reconciler.html
**AP2/Policy Mandate export:** yes

## Request body

- object
  - `older_transfer_fee` object, required: Schedule used before the switch epoch: { epoch, maximum_fee, transfer_fee_basis_points }, all decimal strings (u64; basis points u16).
    - `epoch` string
    - `maximum_fee` string
    - `transfer_fee_basis_points` string
  - `newer_transfer_fee` object, required: Schedule used from its epoch on: { epoch, maximum_fee, transfer_fee_basis_points }, all decimal strings. Applies when execution_epoch >= this epoch.
    - `epoch` string
    - `maximum_fee` string
    - `transfer_fee_basis_points` string
  - `amount` string, required: The TransferChecked amount, i.e. pre-fee, in base units. Decimal string in u64 range.
  - `execution_epoch` string, required: The Clock epoch in which the transfer executes. Decimal string in u64 range.
  - `instruction` 'TransferChecked' | 'TransferCheckedWithFee', required: The checked transfer instruction. Unchecked transfers are refused: they fail with MintRequiredForTransfer on a mint carrying the fee extension.
  - `declared_fee` string: TransferCheckedWithFee only: the fee the instruction states. A mismatch is recorded as FeeMismatch.
  - `credited_amount` string, required: What the payment verifier credited, in base units. Decimal string in u64 range.
  - `verifier_epoch` string: Optional: the epoch the verifier used for its fee. A different schedule pick than the execution epoch emits EPOCH_SCHEDULE_DIVERGENCE.
  - `required_amount` string: Optional: the payee's required amount, for the informational x402 consumer view (gross-accept static path vs net-accept balance-delta path).

## Response `200`

Successful tool execution result

- object
  - `consumer_view` object, nullable, required
  - `credited_amount` string
  - `credited_minus_net` string, nullable, required
  - `declared_fee` string, nullable
  - `detail` string
  - `domain_errors` object[]
    - `code` string, required
    - `text` string, required
  - `epoch_race` string, nullable, required
  - `error` string
  - `execution_epoch` string
  - `fee` string, nullable, required
  - `fee_mismatch` string, nullable
  - `min_pre_fee_for_net` string, nullable, required
  - `net` string, nullable, required
  - `note` string
  - `reconciliation` 'MATCH' | 'OVER_CREDITED' | 'null', nullable, required
  - `schedule` 'newer' | 'older' | 'null', nullable, required
  - `verifier_epoch` string, nullable
  - `withheld_added` string, nullable, required

---

[API](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite.md) · [All operations](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/llms.txt) · [OpenAPI document](https://skmtc.dev/ainumbers/apis/ainumbers-co-fintech-intelligence-suite/revisions/b462e4f5bb28?raw)