@jadonamite/automata-core

Embedded cross-chain SDK for Automata — no backend required.

Bring your own RPC URLs and get direct access to balance reads, USDC bridging (Circle CCTP V2), token swaps (LI.FI + Stellar DEX), transfers, yield opportunities (Aave V3 + LI.FI Earn), and an optional Gemini AI agent — all from a single class.

Installation

npm install @jadonamite/automata-core

Requires Node.js 18+. Peer dependencies: viem, @stellar/stellar-sdk, @lifi/sdk, @google/generative-ai are bundled.

Quick Start

import { AutomataCore } from '@jadonamite/automata-core'

const sdk = new AutomataCore({
  rpc: {
    base:     'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
    celo:     'https://celo-mainnet.g.alchemy.com/v2/YOUR_KEY',
    ethereum: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
  },
})

// Get balances across all chains
const balances = await sdk.getBalances('0x...', 'G...')
// { base: { ETH: '0.041', USDC: '100.00' }, celo: {...}, ethereum: {...}, stellar: { XLM: '94.2' } }

// Build a bridge transaction (returns unsigned tx — you sign it)
const result = await sdk.buildBridgeTx({
  fromChain:        'base',
  toChain:          'celo',
  amount:           '50',
  walletAddress:    '0x...',
  recipientAddress: '0x...',
})

Configuration

const sdk = new AutomataCore({
  rpc: {
    base:     'https://...',  // required
    celo:     'https://...',  // required
    ethereum: 'https://...',  // required
  },
  stellar: {
    horizonUrl: 'https://horizon.stellar.org',      // optional, defaults to mainnet
    sorobanUrl: 'https://soroban-rpc.stellar.org',  // optional, defaults to mainnet
  },
  lifi: {
    integrator: 'your-app-name',  // optional
    apiKey:     'your-lifi-key',  // optional, increases rate limits
  },
})

API Reference

Balances

const balances = await sdk.getBalances(
  evmAddress,     // '0x...' — reads Base, Celo, Ethereum
  stellarAddress  // 'G...' — optional, reads Stellar
)
// Returns: { base, celo, ethereum, stellar } — each a { token: amount } map

Routing

Find the best route for a cross-chain or same-chain swap before building the transaction.

const route = await sdk.getRoute({
  fromChain:     'base',
  toChain:       'celo',
  fromToken:     'USDC',
  toToken:       'CELO',
  amount:        '100',
  walletAddress: '0x...',
})
// { routeId, estimatedOutput, estimatedFeeUSD, estimatedTimeSeconds, steps }

Supported tokens: USDC, ETH, CELO, cUSD, cKES, XLM, EURC, yXLM

Bridge (Circle CCTP V2)

Moves native USDC between chains in ~90 seconds via burn-and-mint. Returns two unsigned transactions: approve + burn.

const result = await sdk.buildBridgeTx({
  fromChain:        'base',       // 'base' | 'celo' | 'ethereum'
  toChain:          'celo',       // 'base' | 'celo' | 'ethereum'
  amount:           '50',
  walletAddress:    '0x...',
  recipientAddress: '0x...',
})
// result.unsignedTxs = [approveTx, burnTx]
// result.summary = { estimatedTimeSeconds: 90, estimatedFeeUSD: '< $0.01', ... }

After the user signs the burn tx, poll for attestation then build the claim tx:

const { message, attestation } = await sdk.pollAttestation(
  6,       // CCTP source domain (base=6, celo=7, ethereum=0)
  '0x...'  // burn tx hash
)

const claimTx = sdk.buildReceiveMessageTx({
  destinationChain: 'celo',
  message,
  attestation,
  amount: '50',
})

Swap

EVM swaps via LI.FI, Stellar swaps via DEX path payment.

// EVM — call getRoute first, then buildSwapTx
const route = await sdk.getRoute({ fromChain: 'base', toChain: 'base', fromToken: 'ETH', toToken: 'USDC', amount: '0.01', walletAddress: '0x...' })
const swap  = await sdk.buildSwapTx({ routeId: route.routeId, walletAddress: '0x...', fromToken: 'ETH', toToken: 'USDC', fromChain: 'base', amount: '0.01' })

// Stellar DEX — no routeId needed
const swap = await sdk.buildSwapTx({
  fromChain:     'stellar',
  fromAddress:   'G...',
  walletAddress: 'G...',
  fromToken:     'XLM',
  toToken:       'USDC',
  amount:        '100',
  minDestAmount: '9.5',
})
// swap.unsignedTx.xdr — sign with Freighter / Privy Stellar wallet

Transfer

Simple token send on any supported chain.

// EVM USDC transfer
const tx = await sdk.buildTransferTx({
  chain:       'base',
  token:       'USDC',
  amount:      '25',
  fromAddress: '0x...',
  toAddress:   '0x...',
})

// Stellar transfer
const tx = await sdk.buildTransferTx({
  chain:       'stellar',
  token:       'XLM',
  amount:      '50',
  fromAddress: 'G...',
  toAddress:   'G...',
})
// tx.unsignedTx.xdr — ready to sign

Yield

Discover live yield opportunities and build deposit transactions via LI.FI Earn.

// Get opportunities — sorted by APY descending
const opportunities = await sdk.getYieldOpportunities('base', 'USDC')

// Build a deposit tx for a specific vault
const result = await sdk.buildStakeTx({
  opportunityId: '8453-0xbeef...',  // vault slug from getYieldOpportunities
  walletAddress: '0x...',
  amount:        '100',
  tokenDecimals: 6,                 // USDC = 6, ETH = 18
})
// result.unsignedTx — approve + deposit, sign sequentially

// Check active positions
const positions = await sdk.getEarnPositions('0x...')

Fee Estimation

const fees = await sdk.estimateFees([
  { type: 'bridge', fromChain: 'base', toChain: 'celo' },
  { type: 'swap',   token: 'USDC' },
])
// { totalEstimatedFeeUSD: '0.60', breakdown: [...], warning: null }

AI Agent (Optional)

Spin up a Gemini-powered agent that drives all the services above from natural language. The agent uses your RPC config — no separate backend needed.

const agent = sdk.createAgent('AIza...')  // your Gemini API key

const { reply, unsignedTxs, updatedHistory } = await agent.chat(
  'Swap 10 USDC to XLM on Stellar',
  [],           // conversation history (empty for new session)
  '0x...',      // EVM wallet address
  'G...',       // Stellar wallet address
)

console.log(reply)
// "Swapping 10 USDC → ~94.2 XLM on the Stellar DEX. Confirm in your wallet."

// Continue the conversation
const next = await agent.chat(
  'Now send 50 XLM to GABCD...',
  updatedHistory,
  '0x...',
  'G...',
)

The agent supports the full tool loop: balance checks → route finding → tx building → fee estimation — all in a single chat() call.

Unsigned Transactions

All tx-building methods return UnsignedTx objects — the SDK never holds private keys.

// EVM — sign with wagmi, viem, ethers, Privy
await sendTransaction({
  to:    unsignedTx.to as `0x${string}`,
  data:  unsignedTx.data as `0x${string}`,
  value: BigInt(unsignedTx.value),
})

// Stellar — sign with Freighter, Privy, or any XDR-compatible wallet
if (unsignedTx.xdr) {
  await signTransaction(unsignedTx.xdr, { network: 'MAINNET' })
}

Supported Chains & Assets

| Chain | EVM | Tokens | |---|---|---| | Base | ✓ | ETH, USDC | | Celo | ✓ | CELO, USDC, cUSD, cKES | | Ethereum | ✓ | ETH, USDC | | Stellar | — | XLM, USDC, EURC, cKES, yXLM |

Related

• @jadonamite/automata-sdk — lightweight API client, wraps a hosted Automata backend
• Automata Platform

License

MIT