Accounts

Overview

@a3stack/accounts removes the biggest barrier to on-chain agent identity: gas fees. Using Coinbase Developer Platform's Paymaster service, agents can register on ERC-8004 with zero ETH — no wallet funding, no gas estimation, no friction.

Under the hood, it creates an ERC-4337 smart account on Base, owned by a CDP-managed server wallet. All transactions are automatically gas-sponsored by the CDP Paymaster.

Installation

$npm install @a3stack/accounts

Requires Node.js 22+ and a CDP account with an API key and Wallet Secret.

CDP Setup

Before using the package, you need three credentials from the CDP portal:

1. API Key ID & Secret — Create at portal.cdp.coinbase.com → API Keys. Enable View and Manage Policies permissions.
2. Wallet Secret — Generate at portal.cdp.coinbase.com → Server Wallet → Accounts. This is an EC P-256 private key (PKCS8 format, base64-encoded).
3. Paymaster Allowlist — Go to portal.cdp.coinbase.com → Paymaster, select Base Mainnet, and add 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 to the contract allowlist.

# .env
CDP_API_KEY_ID=your-api-key-id
CDP_API_KEY_SECRET=your-api-key-secret
CDP_WALLET_SECRET=your-wallet-secret

Quick Start

Create a Smart Account

import { createAgentAccount } from "@a3stack/accounts";

// Create a gasless smart account on Base
const agent = await createAgentAccount({
  apiKeyId: process.env.CDP_API_KEY_ID!,
  apiKeySecret: process.env.CDP_API_KEY_SECRET!,
  walletSecret: process.env.CDP_WALLET_SECRET!,
}, {
  name: "my-agent",  // idempotent — same name returns same account
});

console.log("Smart account:", agent.address);
console.log("Owner EOA:", agent.ownerAddress);
console.log("Network:", agent.network); // "base"

createAgentAccount() is idempotent — calling it with the same name returns the same smart account address every time. The smart account is deployed on-chain with its first UserOperation (CREATE2 deterministic addressing).

Register on ERC-8004

// Register on ERC-8004 with zero gas cost
const result = await agent.register({
  name: "My Agent",
  description: "An autonomous AI agent that does cool things",
  services: [
    { type: "website", url: "https://myagent.ai" },
    { type: "mcp", url: "https://api.myagent.ai/mcp" },
  ],
  x402Support: true,
});

console.log("Tx:", result.transactionHash);
console.log("Gas cost:", result.gasCost);     // 0
console.log("Sponsored:", result.sponsored);  // true

The register() method builds an ERC-8004 registration JSON, encodes it as a data URI, and sends a gasless UserOperation to the registry contract. CDP Paymaster covers all gas costs.

One-Shot Registration

For the simplest flow — create account and register in one call:

import { gaslessRegister } from "@a3stack/accounts";

// One-shot: create account + register in a single call
const result = await gaslessRegister(
  {
    apiKeyId: process.env.CDP_API_KEY_ID!,
    apiKeySecret: process.env.CDP_API_KEY_SECRET!,
    walletSecret: process.env.CDP_WALLET_SECRET!,
  },
  {
    name: "My Agent",
    description: "Registers with zero friction",
    accountName: "my-agent",  // optional
  }
);

console.log("Registered at:", result.smartAccountAddress);
console.log("BaseScan:", `https://basescan.org/tx/${result.transactionHash}`);

Custom UserOperations

The smart account isn't limited to registration — send any gasless transaction via sendUserOperation():

// Send any gasless transaction via the smart account
const result = await agent.sendUserOperation([
  {
    to: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
    value: 0n,
    data: "0x...", // any calldata
  },
]);

console.log("Tx:", result.transactionHash);
// Gas sponsored by CDP Paymaster — $0 cost

API Reference

createAgentAccount(credentials, options?)

Creates or retrieves a gasless smart account on Base.

Returns an AgentAccount with:

• address — Smart account address (ERC-4337)
• ownerAddress — Owner EOA address
• network — "base" or "base-sepolia"
• register(opts) — Register on ERC-8004 (gasless)
• sendUserOperation(calls) — Send any gasless UserOperation

gaslessRegister(credentials, options)

Convenience function that creates an account and registers in one call. Accepts all RegisterOptions plus optional accountName and testnet.

How It Works

1. CDP Server Wallet — Creates a managed EOA (private key secured in CDP's TEE)
2. Smart Account — Creates an ERC-4337 smart account owned by the EOA (deterministic via CREATE2)
3. UserOperation — Encodes the register(agentURI) call and submits it
4. CDP Paymaster — Automatically sponsors the gas fee (you pay $0)
5. Bundler — CDP bundles and submits the UserOperation to Base
6. On-chain — Agent is registered as an ERC-721 NFT on ERC-8004 registry

Supported Networks