@grip-labs/sdk

Money rails for software that spends.

Smart-account wallets, limits, and approvals for autonomous agents on Base. Gas paid in USDC — no ETH needed.

npm install @grip-labs/sdk

Quick start

New here? Follow the step-by-step QUICKSTART.md — a real 5-min path to your first payment, written by the dev who lived the first-user experience.

Are you an AI agent installing this on your own? Read AGENT_INSTALL.md instead — the human only needs to fund a wallet (one tap), the rest is on you.

Easiest mode (managed, zero signups)

import { grip } from '@grip-labs/sdk'

const client = grip.init({
  account: process.env.AGENT_PRIVATE_KEY,
  managed: true, // uses Grip's hosted paymaster proxy — no Pimlico signup
})

That's it. No Pimlico key, no Coinbase signup, no third-party accounts. Fund the wallet with USDC and pay.

Self-managed mode (BYOK Pimlico)

import { grip } from '@grip-labs/sdk'

const client = grip.init({
  account: process.env.AGENT_PRIVATE_KEY, // 0x-prefixed hex pk
  pimlicoApiKey: process.env.GRIP_PIMLICO_KEY, // get one at pimlico.io
  // mode: 'smart' is the default
})

const smartAddress = await client.address()
console.log('Send USDC to:', smartAddress)

const wad = await client.openWad({
  agentId: 'pi-research',
  dailyCap: 25,
  perTxCap: 20,
  allowlist: ['0x46c3519bf9A9F3Dc588191Bc0a5043B5202C3E0A'],
  expiresIn: '30d',
})

const result = await wad.pay({
  to: '0x46c3519bf9A9F3Dc588191Bc0a5043B5202C3E0A',
  amount: 2.50,
})
console.log(result.basescanUrl)

That's it. The agent never holds ETH. Gas is paid in USDC by the smart account itself, no top-up needed.

What ships in v0.2.0

• Smart account mode (default) — Coinbase Smart Wallet derived from any signer
• Sponsored bootstrap — first UserOp deploys the smart account and sets up the paymaster, gas paid by Grip Labs (~$0.05 one-time CAC per user)
• ERC20 paymaster forever after — every subsequent payment pays its own gas in USDC, no ETH ever required
• Same Wad API as v0.1 — openWad, pay, evaluate, spent all work the same
• Backwards compat — pass mode: 'eoa' to use the v0.1 direct-EOA flow

v0.1 → v0.2 migration

In v0.1, your account was an EOA — that's where USDC sat. In v0.2 smart mode, account is the signer. The USDC sits in a separate smart account address (a Coinbase Smart Wallet contract derived from your signer).

const client = grip.init({ account, mode: 'smart', pimlicoApiKey })

console.log('signer (EOA):     ', client.eoaAddress)
console.log('wallet (smart):   ', await client.address())  // ← fund this

Send USDC to the smart account address. The signer just signs UserOps — it doesn't hold funds.

If you have USDC sitting in your v0.1 EOA, transfer it to the new smart account address with a regular tx.

Modes

mode: 'smart' (default)

The way forward. Smart account + paymaster. Agent never needs ETH.

Required option: pimlicoApiKey (or env var GRIP_PIMLICO_KEY).

mode: 'eoa' (v0.1 compat)

Direct EOA signing. Agent holds and signs from a regular EOA. Requires ETH for gas. Use this only for v0.1 backwards compatibility or environments where smart accounts aren't viable.

API

grip.init(options)

Option	Type	Default	Description
account	0x${string} | viem Account	—	Required. Hex private key or viem Account.
mode	"smart" | "eoa"	"smart"	Account model.
pimlicoApiKey	string	env GRIP_PIMLICO_KEY	Required for smart mode.
network	"base"	"base"	Currently only Base mainnet.
rpc	string	https://mainnet.base.org	Custom RPC URL.

Returns: client object. Methods differ slightly between modes:

Method	smart mode	eoa mode
client.address	async () => 0x... (smart account)	0x... (EOA, sync)
client.balance()	reads smart account USDC	reads EOA USDC
client.openWad(opts)	async, returns SmartWad	sync, returns Wad
client.state()	smart-mode only — bootstrap status	—
client.eoaAddress	smart-mode only — underlying signer	—

client.openWad(options)

Option	Type	Default	Description
agentId	string	agent-<timestamp>	Identifier for logging.
dailyCap	number	100	USD per UTC day.
perTxCap	number	20	USD per transaction.
allowlist	0x${string}[]	[]	Empty = open mode.
expiresIn	string | Date	—	"30d", "12h", "30m", or a Date.

wad.pay({ to, amount })

In smart mode, the first pay() triggers a one-time bootstrap (sponsored) and then the actual transfer (gas paid in USDC).

{
  hash, opHash, status: 'confirmed' | 'failed',
  basescanUrl, blockNumber,
  bootstrapTxHash,  // tx hash of the bootstrap, null if already done
  paymaster,        // address of the paymaster that paid gas
}

Throws GripPolicyError if caps or allowlist would be violated.

How sponsored bootstrap works

When a smart account uses Grip for the first time:

1. SDK detects no on-chain code at the smart account address (or no paymaster allowance).
2. SDK constructs a UserOp that deploys the smart account AND approves the Pimlico paymaster for max USDC.
3. The UserOp is sponsored — Grip Labs pays the gas (~$0.05 USD) via Pimlico's verifying paymaster.
4. After this single bootstrap, every subsequent UserOp uses the ERC20 paymaster mode: the user's smart account pays gas itself in USDC. No more sponsorship needed.

So: $0.05 of CAC for us per new user, then sustainable forever. Users never need ETH.

On-chain context

Live on Base mainnet (chain 8453):

Contract	Address
AgentDID	0x2998b171DdE4AA87ae66AaeF8580875270D27B9b
ServiceEscrow	0x1A8B14357187aDE27A9e042269C53576e08E7f8D
SessionKeyManager	0x770A702C2F0CECBD1f54513fBE850e75FCC76BF8
AgentRegistry	0xaCeaB1d37bc6450348C8599ce407ad339F4f40E4
GripPaymaster	0x4351c497ac1d62e2664E4e46D3731c3602d33463
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

External deps (validated on mainnet):

	Address
EntryPoint v0.6	0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
Pimlico paymaster (v0.6)	0x6666666666667849c56f2850848cE1C4da65c68b

import { CONTRACTS } from '@grip-labs/sdk'
console.log(CONTRACTS.base.SessionKeyManager)

Roadmap

• v0.2.x — smart account + sponsored bootstrap + ERC20 paymaster (current)
• v0.3.x — caps enforced on-chain via SessionKeyManager
• v0.4.x — Telegram approval cards for cap-exceeded payments
• v0.5.x — passkey signers (consumer mode), email recovery, fiat onramp partners
• v1.0 — multi-chain (Arbitrum, Optimism), batched recipients, off-chain rails

License

MIT — Copyright (c) 2026 Grip Labs

Track progress at grip.wtf. Protocol contracts at github.com/grip-foundation/protocol.