DevelopersQuickstart
DeFi appSwap, send sponsored transfers, and manage recurring buys and transaction rulesOverviewStart building with native frame transactionsQuickstartSet up the workspace and run a first transactionCreate a clientGive your existing viem client a native frame-transaction workflow. Keep your transport, chain configuration, and familiar public actions.Compose a transferChoose a recipient, draft limits, and who should pay for gas. FramePay generates the verification and execution frames for an EOA ETH transfer.Prepare a transactionBuild an unsigned frame transaction with explicit actions, gas limits, and fee bounds. The client checks the chain and resolves the ordinary account nonce.Sign locallyDelegate authorization to your signer while preserving the transaction you prepared. FramePay rejects changes to the signed envelope.Submit to the sidecarSend a signed frame transaction through the gateway’s standard alternative-mempool path. Get the expected transaction hash without silently retrying writes.Read frame receiptsDistinguish inclusion from successful execution. Inspect individual frame results or wait until every returned frame has succeeded.Inspect admissionRead the sidecar’s retained admission decision and rule checks. Find the stage that rejected a transaction without guessing from a generic RPC error.PlaygroundCreate an account and test the SDK on your local devnet
Search FramePay documentation esc to close
GET STARTED

Your first frame transaction.

Go from a local workspace to a signed transaction, then follow it through the sidecar and into a block.

Local workspace preview

The package is not published to npm yet. These steps use this repository and the installed dependencies in the sibling workshop checkout.

01Set up the workspace

Use Node 20.12 or later and the prepared local workshop. The bootstrap links its pinned dependencies without changing the workshop.

Terminal · FramePay directory
npm run sdk:bootstrapnpm test

The app defaults to the configured Cloudflare gateway on chain 1337. Local Docker is not required. Network identity includes the genesis hash.

02Extend your viem client

client.ts
import { createPublicClient, defineChain, http } from 'viem';import { frameActions, frameNetworks } from '@framepay/sdk';const network = frameNetworks.devnet; // selected FramePay RPCconst chain = defineChain({  id: network.chainId,  name: network.name,  nativeCurrency: { name: 'Test Ether', symbol: 'ETH', decimals: 18 },  rpcUrls: { default: { http: [network.rpcUrl] } },});const client = createPublicClient({  chain,  transport: http(network.rpcUrl, { retryCount: 0 }),}).extend(frameActions({ profile: 'ethrex-eip8141-tracer' }));

03Open the DeFi app

Build the ETHFalcon browser signer using Emscripten 3.1.74, then start the app. The configured devnet already has public deployment records for the wallet factory, paymaster and Aqua market.

Terminal
npm run aqua:bootstrapnpm run quantum:buildnpm run poc:bootstrapnpm run poc:dev

Open the app, create a quantum wallet, deploy it, claim test tokens and review a swap or transfer. Each submitted action checks its receipt and every frame result.

04Try the browser playground

Select Framecraft devnet or Public alt-mempool devnet in the top bar. Both use chain ID 1337 but have separate histories, accounts and deployments. Neither selection requires local Docker.

Create a disposable account in this tab, fund it using the devnet faucet, and walk through the SDK one action at a time. Choose self-payment or request a deployed paymaster, set draft limits, then review the generated frames before signing. The account uses SECP256K1 authorization.

Open playground

05Deploy a test paymaster

From the FramePay directory, deploy the included artifact to the selected network. The script creates a separate deployment key, requests faucet funding, and funds the paymaster with 0.01 test ETH.

Terminal · choose a network
npm run paymaster:deploy -- --network devnet# Or use the separate public alt-mempool devnet:npm run paymaster:deploy -- --network public

After a successful deployment, the script records its receipt, code hash and genesis in config/paymasters.json. The playground then offers “Use deployed FramePay paymaster” for that network. Run the dev server or rebuild a production frontend after updating this file.

This is an open test sponsor: anyone can consume its finite budget, subject to a 0.001 ETH maximum transaction cost. It does not provide allowlisted sponsorship, token reimbursement or automatic refills. Its policy depends on the ethrex profile’s MAX_COST extension.

If a deployment response is lost, rerun the same command to inspect the saved transaction hash. The script does not automatically send a second deployment. A chain reset or source change requires reviewing the old record before a new deployment.

EXPLORE THE APIPrepare a transaction