KOTYTECH.

Verify USDC payments on Base.

Match a transfer against your invoice or payment intent. Get independent evidence of the token, sender, recipient, exact amount and chain finality in one API response.

Try the unpaid request

Match the intended transfer

Provide the transaction hash, native USDC contract, expected recipient and amount in atomic units. Include the sender when it must match. Base Mainnet and Base Sepolia are supported verification networks. API fees are paid on Base Mainnet.

Reconcile with two RPC providers

The API reports execution, transfer matching and finality. A positive result requires one exact transfer, successful execution and finalized evidence. Your application can hold the invoice when evidence is pending or uncertain.

Request a payment challenge

This example uses synthetic transaction details. The unpaid request returns HTTP 402 with a Payment-Required header. Substitute your own transaction and expected values when integrating.

curlPOST /v1/payments/verify
curl -i --request POST 'https://api.kotytech.co/v1/payments/verify' \
  --header 'Content-Type: application/json' \
  --data '{
    "network": "eip155:8453",
    "transactionHash": "0xba1d0239f3e8bb67c26ed25f05feb1bacdf4ec3054a56c397a13c18e30bbec61",
    "expectedRecipient": "0x2000000000000000000000000000000000000002",
    "expectedTokenContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "expectedAmountAtomic": "10000"
  }'
TypeScript integration

Install @x402/core@2.30.0 and @x402/evm@2.30.0 in your Node.js project. Call verifyOnce(input, signer, approveFee) with your wallet-backed ClientEvmSigner. Have approveFee return true only after the payer confirms the displayed terms.

The example checks the quoted fee and sends the same JSON once with its payment authorization. Keep the verification transaction hash and the returned API fee transaction hash as separate records.

import { x402Client } from "@x402/core/client";
import { decodePaymentRequiredHeader, decodePaymentResponseHeader, encodePaymentSignatureHeader, readLimitedText } from "@x402/core/http";
import { PaymentRequiredV2Schema } from "@x402/core/schemas";
import type { ClientEvmSigner } from "@x402/evm";
import { ExactEvmScheme } from "@x402/evm/exact/client";

const endpoint = "https://api.kotytech.co/v1/payments/verify";
const fee = {
  network: "eip155:8453",
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  recipient: "0xBeb25e74d68104CE91BF269842c97507275aDBb1",
  amountAtomic: "5000",
} as const;
const lower = (value: unknown) => typeof value === "string" ? value.toLowerCase() : undefined;

export type VerificationInput = {
  network: "eip155:8453" | "eip155:84532";
  transactionHash: `0x${string}`;
  expectedRecipient: `0x${string}`;
  expectedTokenContract: `0x${string}`;
  expectedAmountAtomic: string;
  expectedSender?: `0x${string}`;
};

/** Use a wallet-backed signer. Each call can submit one authorized API fee. */
export async function verifyOnce(
  input: VerificationInput,
  signer: ClientEvmSigner,
  approveFee: (terms: typeof fee & { payer: ClientEvmSigner["address"] }) => Promise<boolean>,
  request: typeof fetch = fetch,
) {
  const body = JSON.stringify(input);
  const { network, transactionHash } = input;
  const payer = signer.address;
  const contentType = { "Content-Type": "application/json" };
  const post = (headers: Record<string, string>, timeout: number) =>
    request(endpoint, { method: "POST", redirect: "error", headers, body, signal: AbortSignal.timeout(timeout) });

  const unpaid = await post(contentType, 10_000);
  const encodedQuote = unpaid.headers.get("Payment-Required");
  await readLimitedText(unpaid, 32_768);
  if (unpaid.status !== 402 || !encodedQuote) throw new Error(`Payment quote unavailable (HTTP ${unpaid.status}).`);
  const quote = decodePaymentRequiredHeader(encodedQuote);
  PaymentRequiredV2Schema.parse(quote);
  const [option] = quote.accepts;
  const admission = quote.extensions?.kotytechPaymentAdmission as { enabled?: boolean } | undefined;
  if (quote.resource.url !== endpoint || quote.resource.mimeType !== "application/json" || admission?.enabled !== true ||
      quote.accepts.length !== 1 || option?.scheme !== "exact" || option.network !== fee.network ||
      option.amount !== fee.amountAtomic || lower(option.asset) !== lower(fee.asset) || lower(option.payTo) !== lower(fee.recipient) ||
      !Number.isInteger(option.maxTimeoutSeconds) || option.maxTimeoutSeconds < 1 || option.maxTimeoutSeconds > 120 ||
      option.extra?.assetTransferMethod !== "eip3009" || option.extra.paymentFlow !== "authorization" ||
      option.extra.name !== "USD Coin" || option.extra.version !== "2") {
    throw new Error("The active quote does not match the expected Base Mainnet USDC terms.");
  }
  if (await approveFee({ ...fee, payer }) !== true) throw new Error("Payment was declined.");

  const client = new x402Client().register(fee.network, new ExactEvmScheme({
    address: payer,
    async signTypedData(data) {
      if (data.primaryType !== "TransferWithAuthorization" || data.domain.chainId !== 8453 ||
          data.domain.name !== "USD Coin" || data.domain.version !== "2" ||
          lower(data.domain.verifyingContract) !== lower(fee.asset) || lower(data.message.from) !== lower(payer) ||
          lower(data.message.to) !== lower(fee.recipient) || data.message.value !== 5000n) {
        throw new Error("Wallet signing terms differ from the approved API fee.");
      }
      return signer.signTypedData(data);
    },
  }));
  const { bazaar } = quote.extensions ?? {};
  const proof = encodePaymentSignatureHeader(await client.createPaymentPayload({
    ...quote, extensions: bazaar ? { bazaar } : {},
  }));
  if (proof.length > 8192) throw new Error("The payment authorization exceeds the API header limit.");

  try {
    const response = await post({ ...contentType, "Payment-Signature": proof }, 50_000);
    const requestId = response.headers.get("X-Request-ID");
    const encodedReceipt = response.headers.get("Payment-Response");
    const text = await readLimitedText(response, 32_768);
    if (response.status !== 200 || !encodedReceipt) {
      throw new Error(`HTTP ${response.status}, request ID ${requestId ?? "unavailable"}`);
    }
    const receipt = decodePaymentResponseHeader(encodedReceipt);
    const decision = JSON.parse(text);
    if (receipt.success !== true || receipt.network !== fee.network ||
        (receipt.amount !== undefined && receipt.amount !== fee.amountAtomic) || !/^0x[0-9a-fA-F]{64}$/.test(receipt.transaction) ||
        typeof decision.verified !== "boolean" || decision.network !== network ||
        lower(decision.transactionHash) !== lower(transactionHash) ||
        decision.verificationPolicy !== "one_exact_usdc_transfer_and_finalized") {
      throw new Error("The response does not match the verification request and its fee.");
    }
    return { decision, feeTransactionHash: receipt.transaction, requestId };
  } catch (cause) {
    throw new Error("Payment outcome requires reconciliation before another attempt.", { cause });
  }
}

Interpret the response

A completed verification may be negative, pending or uncertain and can still incur the quoted fee. Credit an invoice only when verified is true and the returned transfer matches your records.

200
Verification result. Inspect verified, transfer evidence and finality.
400
Correct the request fields or payment authorization format.
402
Read Payment-Required for a quote. If a signed request failed, inspect the response and reconcile its payment before creating another authorization.
429
Respect Retry-After when present. Reconcile any pending signed attempt before retrying.
502 / 503
Inspect the error and request ID. A dependency may be unavailable or admission held. Reconcile any signed attempt before proceeding.

Read the complete request and response schemas