Lycoris · Settle Kit

USDC payments for people and agents. Built into your app.

A TypeScript SDK for checkout, paid agent requests, and payment-protected APIs. Lycoris is the working demo: a person and an AI agent buy the same weather report.

Try checkout · Watch an agent pay · Documentation · Payment feed

Start with the guided tour · Engineering case study

Base Sepolia · Test USDC · Experimental SDK · Not published to npm

Why

Sending a transaction is the easy part. An application has to bind an amount to a destination, check the balance before asking for a signature, survive a rejected wallet, wait for a receipt, and decide when the buyer actually gets the thing. An agent needs permission to spend on top of all that.

Settle Kit puts each of those behind a small, separate API. You keep your wallet, your credentials, your authorization policy, and your UI.

The weather report makes it concrete: both demos buy Melbourne's next 1 PM forecast for 0.1 test USDC, from the same merchant, down two different paths.

See it working

Follow one path: buy a report → let an agent buy it → see an over-limit purchase refused → inspect the decision evidence. The guided tour links each step and explains what to look for. Its overview takes about 90 seconds; live purchases also wait for the agent and network. Walkthrough script.

Page	Try	Shows
Checkout	Click Pay, or switch to your wallet, then read the report	A confirmed transfer on a sponsored 4337 rail or an injected EOA
Agent demo	Pick a scenario, hit Get me the report	An agent buying over x402, through identity, mandate and balance gates
Feed	Browse commitments and disclosed evidence	How the facilitator records what it decided, and why

Checkout has two host rails and one verb. Demo pays uses a CDP faucet and a paymaster so a browser-owned smart account can send 0.1 test USDC without a personal wallet. Your wallet is Coinbase Wallet or another injected EOA; you send the transfer and pay gas. These are real testnet transactions. The faucet reserves at most 50 funded purchases / 5 test USDC per sponsor; gas sponsorship has separate provider limits. Report access lasts 15 minutes. Exhaustion makes the sponsored rail unavailable; it does not switch to a simulation. See setup and recovery.

Packages

Package	Does
@settle-kit/core	Headless sessions, balance preflight, transfer, receipt confirmation	→
@settle-kit/react	SettleProvider, useCheckout, optional UI with compiled CSS	→
@settle-kit/agents	x402 paid fetch and AP2 mandate helpers	→
@settle-kit/server	A Next.js paid-route wrapper	→
@settle-kit/mcp	A local stdio MCP server that buys x402-gated resources	→

React 19 and viem 2. ESM and type declarations, no transpilePackages needed. The optional UI drags in no wagmi, Zustand, shadcn or Tailwind. The MCP server speaks protocol revision 2026-07-28 and refuses older clients.

Add checkout

Packages live in this workspace. After bun run build --filter=@settle-kit/react, point a host package.json at packages/settle-kit/* with a matching overrides entry. Then mount one provider:

"use client";

import { SettleProvider, type PaymentSigner } from "@settle-kit/react";
import { Checkout } from "@settle-kit/react/ui";
import "@settle-kit/react/styles.css";

export function Store({ getSigner }: { getSigner: () => Promise<PaymentSigner> }) {
  return (
    <SettleProvider
      config={{
        appName: "Your store",
        getSigner,
        destination: {
          targetChain: 84532,
          targetAsset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          recipient: "0x1111111111111111111111111111111111111111", // yours
        },
      }}
    >
      <Checkout amount="0.1" title="Weather report" />
    </SettleProvider>
  );
}

getSigner returns an address and sendTransaction. That is the entire wallet contract. The host puts the wallet on Base Sepolia. Pass method when the host wraps createUsdcMethod — for sponsorship, for example.

Examples

Pick the smallest thing that works. Every path shares the same session semantics and error codes — they differ only in who renders and who decides price.

Your own checkout UI

useCheckout() is the session as a state machine. One branch per status and the whole lifecycle is covered. #custom-ui

"use client";
import { useCheckout } from "@settle-kit/react";

export function BuyReport() {
  const { state, pay, reset, retryConfirmation } = useCheckout();
  switch (state.status) {
    case "idle":
      return <button onClick={() => void pay({ amount: "0.1" })}>Pay 0.1 USDC</button>;
    case "settling":
      return state.confirmationError
        ? <button onClick={() => void retryConfirmation()}>Check payment status</button>
        : <p>Waiting for your wallet and confirmation…</p>;
    case "settled":
      return <><p>Payment confirmed.</p><button onClick={reset}>New purchase</button></>;
    case "failed":
      return <><p role="alert">{state.error.message}</p><button onClick={reset}>Reset</button></>;
  }
}

pay({ amount }) prepares, sends, and waits for a receipt. If the receipt is missing, call retryConfirmation() — do not send again.

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗