Hello Moon Ink paymaster SDK

TypeScript SDK for two explicit paymaster modes on Ink Mainnet:

• public prepaid USDC, USD₮0, or USDG reimbursement through /public/quote; and
• authenticated native-gas sponsorship through the ERC-7677 /sponsor/rpc endpoint.

Both modes submit through the Alto ERC-4337 bundler at /public/rpc. Alto is not a paymaster. Each separate paymaster contract supplies native gas through EntryPoint v0.7; only prepaid mode receives ERC-20 reimbursement from the smart account.

EIP-7702 is available through the explicit INK_PUBLIC_PAYMASTER_V08 deployment. The original INK_PUBLIC_PAYMASTER constant remains pinned to EntryPoint v0.7 for existing integrations.

Requirements

• Node.js 20 or newer;
• Viem >=2.55.18 <3; and
• an EntryPoint-compatible smart account, or an EOA using the v0.8 EIP-7702 deployment;

Prepaid mode additionally requires an enabled reimbursement token and a finite allowance for that token. Sponsored mode instead requires a sponsorship-enabled API key stored only in trusted backend infrastructure.

The public paymaster does not sponsor its own approval. encodePublicPaymasterApproval only encodes an approval that the account must execute using its own gas or another sponsorship mechanism. Quote-v4 atomic EIP-2612 permits are implemented for the next reviewed deployment; they are not active on either currently pinned public deployment constant.

Authenticated native sponsorship

import {http} from "viem";
import {createBundlerClient} from "viem/account-abstraction";
import {
  createInkSponsoredPaymasterClient,
  INK_SPONSORED_PAYMASTER,
} from "@hellomoon/ink-paymaster";

const paymaster = createInkSponsoredPaymasterClient({
  apiKey: process.env.INK_SPONSOR_API_KEY!,
});
const bundler = createBundlerClient({
  account,
  chain: ink,
  client: publicClient,
  transport: http(
    `${INK_SPONSORED_PAYMASTER.serviceUrl}${INK_SPONSORED_PAYMASTER.bundlerPath}`,
  ),
  paymaster,
  paymasterContext: {idempotencyKey: "checkout-0xabc-7"},
});

The returned Viem Paymaster Client implements pm_getPaymasterStubData and pm_getPaymasterData against /sponsor/rpc. The API key authorizes sponsorship policy; the smart account still signs the final UserOperation. Never put this key in browser or mobile code.

Prepare, sign, and submit

import {createInkPublicPaymasterClient} from "@hellomoon/ink-paymaster";

const paymaster = createInkPublicPaymasterClient();

const prepared = await paymaster.prepareUserOperation({
  userOperation: operationWithYourCorrectlySizedStubSignature,
  maxTokenCost: 100_000n, // 0.1 USDC; USDC has six decimals
});

// Sign only after quote fields and estimated gas fields are applied.
const signed = await yourAccount.signUserOperation(prepared.userOperation);
const hash = await paymaster.sendUserOperation(signed);
const receipt = await paymaster.waitForUserOperationReceipt({hash});

prepareUserOperation returns the idempotency key and quote metadata with the operation. Persist those values with the eventual UserOperation hash and transaction receipt.

Viem Bundler Client

For prepaid mode, the SDK exposes a Viem paymaster hook. Pass the reimbursement ceiling through paymasterContext:

import {http} from "viem";
import {createBundlerClient} from "viem/account-abstraction";
import {
  createInkPublicPaymasterClient,
  createInkViemPaymaster,
  INK_PUBLIC_PAYMASTER,
} from "@hellomoon/ink-paymaster";

const service = createInkPublicPaymasterClient();
const bundler = createBundlerClient({
  account,
  chain: ink,
  client: publicClient,
  transport: http(`${INK_PUBLIC_PAYMASTER.serviceUrl}/public/rpc`),
  paymaster: createInkViemPaymaster(service),
  paymasterContext: {
    maxTokenCost: 100_000n,
    idempotencyKey: "checkout-0xabc-7",
  },
});

Account state and settlement

import {
  encodePublicPaymasterApproval,
  getPublicPaymasterAccountState,
} from "@hellomoon/ink-paymaster";

const state = await getPublicPaymasterAccountState(publicClient, smartAccountAddress);
const approvalCall = encodePublicPaymasterApproval(1_000_000n);

Unused precharge becomes pull-based refund credit. Use encodePublicPaymasterRefundClaim to encode the paymaster call; the smart account that owns the credit must execute it.

Documentation site

The editable guide is in docs, with type-checked sponsored, prepaid, approval, and multi-token transfer examples in examples. Preview it locally with:

pnpm docs:dev

Generate the API reference and production site with pnpm docs:build. TypeDoc creates the API pages from TSDoc comments on public exports; VitePress builds the handwritten guides around them.

Generate the distributable PDF integration guide from the repository root with:

python3 scripts/build-sdk-integration-guide.py

The builder requires ReportLab and uses Verdana/Andale Mono on macOS or DejaVu Sans/Mono on Linux. It writes output/pdf/ink-paymaster-sdk-integration-guide.pdf.

Tests

pnpm test
pnpm typecheck
pnpm typecheck:examples
pnpm docs:build
pnpm build

The default integration suite runs against isolated HTTP servers. It asserts the prepaid quote and bundler routes as well as both authenticated ERC-7677 methods, bearer authorization, context forwarding, response parsing, quote validation, and gas-estimate merging. The opt-in live test performs only read-only public health and bundler checks:

pnpm test:live

The funded end-to-end test is separately gated because it submits two real UserOperations: an owner-paid finite USDC approval when needed, followed by a one-base-unit prepaid transfer through the public quote and bundler routes. It requires a controlled deployed smart account:

INK_PAYMASTER_TEST_OWNER_PRIVATE_KEY=0x... \
INK_PAYMASTER_TEST_SMART_ACCOUNT=0x... \
pnpm test:funded

Verified public canary

The funded SDK integration test landed successfully on Ink Mainnet on 2026-09-10 using only the public routes:

Smart account:         0x1c9E6fA23C156262949658c500946d68A0646770
Approval transaction:  0xc46d223bd5ad992b1e77c6c716cb0559ce522d3452b034d58418f7ae2be610b9
Prepaid UserOperation: 0x5fe0014b21b8e4260e2d683d0d2c6588891b21b5b690ee6e6d555ad8d8009498
EntryPoint transaction:0x6b474b6e59b0c677d0325279577f156ef99a602081c9dc996dba180a517f4b7d

The owner-paid approval used 185,625,792,812 wei. The prepaid operation transferred one USDC base unit, prepaid 1,224, added 558 to refund credit, and therefore settled 666 base units as the paymaster's actual reimbursement. Both transaction receipts succeeded.