Abstract Onboard

Everything an AI agent needs to operate on Abstract (ZK Stack L2).

🚀 New Agent? Start Here

# Check if you're ready to operate
node scripts/quick-start.js check \x3Cyour-wallet-address>

# Or get the full setup guide
node scripts/quick-start.js

Quick Start

Create Abstract Global Wallet (AGW)

AGW is a smart contract wallet that earns XP on Abstract. Essential for agents!

⚠️ CRITICAL: Understand the 3 layers first:

Private Key → EOA (signer) → AGW (smart contract wallet)

The correct funding flow:

1. Fund EOA with small ETH (for gas)
2. Create/deploy AGW (EOA pays gas for first tx)
3. Fund AGW with your main balance
4. Everything runs through AGW from now on

export WALLET_PRIVATE_KEY=0x...
node scripts/create-agw.js

Your EOA becomes the signer, AGW is a separate smart contract address.

⚠️ Version Warning: Different agw-client versions may compute different AGW addresses! Always pin your version. See references/agw.md for details.

Check Balances

node scripts/check-balances.js \x3Cwallet> all

Bridge ETH to Abstract

export WALLET_PRIVATE_KEY=0x...
node scripts/relay-bridge.js --from base --amount 0.01

Deploy a Contract

export WALLET_PRIVATE_KEY=0x...
node scripts/deploy-abstract.js ./artifacts/MyContract.json "constructor-arg"

Transfer Tokens

export WALLET_PRIVATE_KEY=0x...
node scripts/transfer.js --to 0x... --amount 0.01           # ETH
node scripts/transfer.js --to 0x... --amount 100 --token USDC  # Token

Swap Tokens

export WALLET_PRIVATE_KEY=0x...
export DEX_ROUTER=0x...  # Set DEX router address
node scripts/swap-tokens.js --from ETH --to USDC --amount 0.01

DEX Trading (Kona & Aborean)

Abstract has multiple DEXs. Use the protocol-specific scripts for best results:

# Kona Finance (V2) - USDC → ETH
export WALLET_PRIVATE_KEY=0x...
node scripts/swap-kona.js

# Aborean (Velodrome-style) - when router is available
node scripts/swap-aborean.js

# Generic Uniswap V2
node scripts/swap-uniswap-v2.js

See references/dex.md for contract addresses and supported pools.

Myriad Prediction Markets

Trade on Myriad Markets — the largest prediction market on Abstract (415K+ users, $100M+ volume).

# List open markets
node scripts/myriad-trade.js list

# Get market details
node scripts/myriad-trade.js info \x3CmarketId>

# Buy shares (place a prediction)
export WALLET_PRIVATE_KEY=0x...
node scripts/myriad-buy-direct.js \x3CmarketId> \x3CoutcomeId> \x3Camount>

# Example: $1 USDC.e on "Yes" for market 765
node scripts/myriad-buy-direct.js 765 0 1

See references/myriad.md for contract addresses, ABI details, and token info.

Call Any Contract

# Read
node scripts/call-contract.js --address 0x... --abi ./abi.json --function balanceOf --args 0x1234

# Write
export WALLET_PRIVATE_KEY=0x...
node scripts/call-contract.js --address 0x... --abi ./abi.json --function transfer --args 0x1234,100 --write

Mint NFT

# Deploy SimpleNFT.sol first, then mint
export WALLET_PRIVATE_KEY=0x...

# Mint to existing contract
node scripts/mint-nft.js --contract 0x... --image QmIPFShash --to 0xRecipient --name "My NFT"

See references/SimpleNFT.sol for a basic NFT contract template.

USDC Operations

# Check USDC balance
node scripts/usdc-ops.js balance \x3Cwallet>

# Transfer USDC
export WALLET_PRIVATE_KEY=0x...
node scripts/usdc-ops.js transfer \x3Cto> \x3Camount>

# Approve spender
node scripts/usdc-ops.js approve \x3Cspender> \x3Camount>

# Check allowance
node scripts/usdc-ops.js allowance \x3Cowner> \x3Cspender>

Estimate Gas

# Get current gas prices
node scripts/estimate-gas.js

# Estimate transfer cost
node scripts/estimate-gas.js transfer \x3Cto> \x3Camount>

# Estimate deployment cost
node scripts/estimate-gas.js deploy \x3CbytecodeSize>

Watch Events

# Watch new blocks
node scripts/watch-events.js blocks

# Watch ETH transfers to/from wallet
node scripts/watch-events.js transfers \x3Cwallet>

# Watch ERC20 transfers
node scripts/watch-events.js erc20 \x3Ctoken> \x3Cwallet>

# Watch contract events
node scripts/watch-events.js contract \x3Caddress>

Testnet Setup

# Get faucet instructions
node scripts/testnet-setup.js faucet

# Check testnet balance
node scripts/testnet-setup.js check \x3Cwallet>

# Verify testnet setup
node scripts/testnet-setup.js verify \x3Cwallet>

Key Information

Scripts

References

⚠️ CRITICAL: Contract Deployment

Abstract is a zkSync-based chain. Standard EVM deployment methods DON'T WORK.

What WORKS ✅

// Use zksync-ethers (NOT viem, NOT standard ethers)
const { ContractFactory } = require("zksync-ethers");
const factory = new ContractFactory(abi, bytecode, wallet);
const contract = await factory.deploy(args);

// ALWAYS verify bytecode after deploy
const code = await provider.getCode(address);
if (code === '0x') throw new Error("Deploy failed!");

What DOESN'T WORK ❌

// DON'T use viem's deployContract
await walletClient.deployContract({...}); // Returns success but NO BYTECODE

// DON'T use standard ethers ContractFactory
// DON'T trust transaction success alone

Deployment Checklist

• Compiled with zksolc (not standard solc)
• Using zksync-ethers ContractFactory
• Verify eth_getCode != 0x after deploy
• Test contract functions before sending tokens

Common Issues

1. Gas estimation fails → Use Hardhat, not foundry-zksync
2. Compiler errors → Use Solidity 0.8.x with zksolc
3. TX stuck → Check gas price, verify on abscan.org
4. Deploy succeeds but no bytecode → Use zksync-ethers, not viem
5. Tokens sent to empty address → Always verify bytecode first!

See references/troubleshooting.md for detailed solutions.

Dependencies

# Core dependencies
npm install ethers zksync-ethers viem

# For contract deployment
npm install @matterlabs/hardhat-zksync

# For AGW (Abstract Global Wallet) - PIN THE VERSION!
# Different versions compute different AGW addresses
npm install @abstract-foundation/[email protected]

⚠️ agw-client version warning: Newer versions may use different factory contracts, computing different AGW addresses for the same EOA. If you change versions, verify your AGW address hasn't changed before sending funds!