Migrating from v1

The legacy @0xgasless/agent-sdk (v0.1) and the new @0xgasless/agent (v2) are different packages. v2 isn’t a drop-in replacement — it represents a different architectural choice. This guide explains the differences and how to migrate.

What changed

	v1 (@0xgasless/agent-sdk)	v2 (@0xgasless/agent)
Wallet custody	Bring-your-own (ethers.Signer, Privy, Safe)	Platform-managed (KMS)
Private keys	Held in your app	Never seen by your app
Policy enforcement	Your responsibility	Server-side, before signing
ERC-8004 registration	Direct contract calls — you pay gas	Sponsored by 0xGasless
LangChain tools	Included	Not included
Session keys	Included	Replaced by per-agent policy
CLI (moltpay)	Included	Not included
Chains	Avalanche only	Avalanche, Fuji, Base
Audit log	None	DynamoDB-backed
Configuration	Network config + signer	Just an API key

The big change: v2 owns the wallet. In v1 your code held a signer; in v2 the platform holds the key in KMS and only signs after enforcing your policy. This is a strict upgrade for autonomous-agent use cases:

• No private keys in your application code.
• No policy logic you have to write yourself.
• No gas-management code.

For use cases where you really do need to hold the signer (e.g. integrating with an existing wallet UX), keep using v1 — it’s still on npm.

Should I migrate?

You’re doing	Recommendation
Building autonomous bots (Telegram, trading, oracles, AI agents)	Migrate to v2. Less code, safer, cheaper.
Building a consumer wallet UX where users hold keys	Stay on v1, or use Embedded Wallets.
Using session keys to constrain a user’s existing wallet	Stay on v1 — session keys are a v1 feature.
You want LangChain getAgentTools()	Stay on v1 until v2 ships its own LangChain integration.
You want a CLI	Stay on v1 (moltpay).

Migration cookbook

If you decide to migrate, here are the most common code patterns mapped one-to-one.

Install

# v1
npm install @0xgasless/agent-sdk

# v2
npm install @0xgasless/agent

Initialise

// v1
import { AgentSDK, fujiConfig } from '@0xgasless/agent-sdk';
import { Wallet, JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://api.avax-test.network/ext/bc/C/rpc');
const wallet   = new Wallet(process.env.PRIVATE_KEY!, provider);
const sdk = new AgentSDK({
  networks:       fujiConfig.networks,
  defaultNetwork: 'fuji',
  signer:         wallet,
});

// v2
import { OxGasAgent } from '@0xgasless/agent';

const client = new OxGasAgent({
  apiKey: process.env.OXGAS_API_KEY!,
});

You stop providing a signer entirely. The platform mints and holds the key for each agent.

Get the agent’s address

// v1 — the signer's own address
const addr = await sdk.getAddress();

// v2 — created on first call, returned in the response
const agent = await client.agents.create({ agentId: 'my-bot' });
console.log(agent.address);

Register ERC-8004 identity

// v1 — you pay the gas
const tx = await sdk.erc8004.identity('fuji').register(agentCardURI);
const receipt = await tx.wait();

// v2 — 0xGasless pays the gas
const identity = await client.identity.link({
  agentId: 'my-bot',
  chain:   'fuji',
});
console.log(identity.agentTokenId);

Pay an x402-enabled API

// v1 — sign locally, then call facilitator
import { createPaymentPayload, FacilitatorClient } from '@0xgasless/agent-sdk';

const facilitator = sdk.getFacilitator('fuji');
const payload = await createPaymentPayload(requirements, wallet, network);
await facilitator.verify(payload, requirements);
const settle  = await facilitator.settle(payload, requirements);

// v2 — one call, server-side signing + policy check
const result = await client.x402.pay({
  agentId: 'my-bot',
  to:      '0xMerchant...',
  value:   '500000',
});

Set policy

// v1 — no built-in policy. You wrote your own limits.
if (amount > MAX_PER_TX) throw new Error('too big');

// v2 — server-side, enforced before signing
await client.policy.setAgent('my-bot', {
  perTxCapUSD:  5,
  perDayCapUSD: 50,
});
// Now any client.x402.pay() that breaches these returns 403 — no signature is produced.

Check balance

// v1 — call ERC-20 directly
const token = new Contract(USDC_ADDRESS, ERC20_ABI, provider);
const bal   = await token.balanceOf(agentAddress);

// v2 — built-in helper
const { balances } = await client.agents.getBalance('my-bot');
console.log(balances.fuji?.usdc);

Revoke

// v1 — no concept of revoke. You'd just stop using the signer.

// v2 — terminal status flip
await client.agents.revoke('my-bot');

Things you’ll lose

• LangChain tools. getAgentTools() and friends aren’t in v2 (yet). Wrap the v2 SDK in your own tools if you need this.
• Wallet abstraction. No Privy or Safe providers in v2 — the platform owns the wallet.
• Session keys. Replaced by per-agent policy. For most use cases that’s strictly better; if you needed session keys for a user-facing wallet, stay on v1.
• The moltpay CLI. Use the dashboard instead.

Both packages can coexist

If you’re partially migrating, both packages can live in the same project — they don’t share state. v1 is @0xgasless/agent-sdk, v2 is @0xgasless/agent. Different import names, different APIs.

Need help?

If something maps oddly, open an issue at github.com/0xgasless/agent-sdk/issues.