Configuring Actions SDK

Learn how to configure Actions SDK for your application.

Actions SDK lets you choose which assets, markets, chains, protocols, and providers you want to support in your application via configuration file.

1. Install Actions SDK

   Follow the quickstart guide to add Actions SDK as a dependency in your app.

2. Integrate an embedded wallet

   Follow the integrating wallets guide, choose and install a Wallet Provider.

3. Create a config file

   actions.ts - An accessible file that holds all of your configuration preference.

4. Configure a Wallet Provider

   Let Actions SDK know which Wallet Provider you’ve chosen:

   Frontend

   Select a wallet provider:

   Privy

   actions.ts

   const walletConfig = {
     hostedWalletConfig: {
       provider: {
         type: "privy" as const,
       },
     },
     smartWalletConfig: {
       provider: {
         type: "default" as const,
         attributionSuffix: "actions",
       },
     },
   };
   

   Turnkey

   actions.ts

   const walletConfig = {
     hostedWalletConfig: {
       provider: {
         type: "turnkey" as const,
       },
     },
     smartWalletConfig: {
       provider: {
         type: "default" as const,
         attributionSuffix: "actions",
       },
     },
   };
   

   Dynamic

   actions.ts

   const walletConfig = {
     hostedWalletConfig: {
       provider: {
         type: "dynamic" as const,
       },
     },
     smartWalletConfig: {
       provider: {
         type: "default" as const,
         attributionSuffix: "actions",
       },
     },
   };
   

   Backend

   Select a wallet provider:

   Privy

   actions.ts

   import { PrivyClient } from '@privy-io/node'
   
   const privyClient = new PrivyClient(
     process.env.PRIVY_APP_ID,
     process.env.PRIVY_APP_SECRET,
   )
   
   const walletConfig = {
     hostedWalletConfig: {
       provider: {
         type: "privy" as const,
         config: {
           privyClient,
         },
       },
     },
     smartWalletConfig: {
       provider: {
         type: "default" as const,
         attributionSuffix: "actions",
       },
     },
   };
   

   Turnkey

   actions.ts

   import { Turnkey } from '@turnkey/sdk-server'
   
   const turnkeyClient = new Turnkey({
     apiBaseUrl: 'https://api.turnkey.com',
     apiPublicKey: process.env.TURNKEY_API_KEY,
     apiPrivateKey: process.env.TURNKEY_API_SECRET,
     defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
   })
   
   const walletConfig = {
     hostedWalletConfig: {
       provider: {
         type: "turnkey" as const,
         config: {
           client: turnkeyClient.apiClient(),
         },
       },
     },
     smartWalletConfig: {
       provider: {
         type: "default" as const,
         attributionSuffix: "actions",
       },
     },
   };
   
5. Configure supported assets

   Configure which assets you want to support across all lend and swap providers:

   actions.ts

   // Additional config from previous steps...
   
   // Import popular assets
   import { USDC } from '@eth-optimism/actions-sdk/assets'
   import type { Asset, AssetsConfig } from "@eth-optimism/actions-sdk";
   
   // Or define custom assets
   export const CustomToken: Asset = {
     address: {
       [mainnet.id]: '0x123...',
       [unichain.id]: '0x456...',
       [baseSepolia.id]: '0x789...',
     },
     metadata: {
       decimals: 6,
       name: 'Custom Token',
       symbol: 'CUSTOM',
     },
     type: 'erc20',
   }
   
   // Configure allowed/blocked assets
   const assetsConfig: AssetsConfig = {
     allow: [USDC, CustomToken],
     block: [],  // Optional
   }
   
6. Configure Markets

   Define which markets you want to support or block within your app:

   actions.ts

   // Additional config from previous steps...
   
   export const GauntletUSDC: LendMarketConfig = {
     address: '0xabc...',
     chainId: unichain.id,
     name: 'Gauntlet USDC',
     asset: USDC,
     lendProvider: 'morpho',
   }
   
7. Configure Lend Providers

   Configure which lend protocols you want to support. You can enable one or multiple providers:

   actions.ts

   // Additional config from previous steps...
   
   import type { LendConfig } from "@eth-optimism/actions-sdk";
   
   const lendConfig: LendConfig = {
     morpho: {
       marketAllowlist: [GauntletUSDC],
       marketBlocklist: [],  // Optional
     },
     aave: {
       marketAllowlist: [AaveWETH],
       marketBlocklist: [],  // Optional
     },
   };
   
8. Configure Swap Providers

   Configure which swap protocols you want to support. Actions SDK supports Uniswap V4 on Ethereum mainnet and OP Stack chains, and Velodrome / Aerodrome on OP Stack chains:

   Uniswap

   actions.ts

   // Additional config from previous steps...
   
   import { UniswapSwapProvider } from "@eth-optimism/actions-sdk";
   import type { SwapConfig } from "@eth-optimism/actions-sdk";
   
   const swapConfig: SwapConfig = {
     uniswap: {
       // Optional: restrict to specific trading pairs
       marketAllowlist: [
         { assets: [USDC, ETH] },
         { assets: [USDC, WETH], chainId: base.id },
       ],
       defaultSlippage: 0.005,   // 0.5% default slippage
       maxSlippage: 0.5,         // 50% max slippage guard
     },
   };
   

   Velodrome / Aerodrome

   actions.ts

   // Additional config from previous steps...
   
   import { VelodromeSwapProvider } from "@eth-optimism/actions-sdk";
   import type { SwapConfig } from "@eth-optimism/actions-sdk";
   
   // Velodrome (Optimism) and Aerodrome (Base) use the same provider.
   // Supported on Optimism, Base, and many OP Stack leaf chains.
   const swapConfig: SwapConfig = {
     velodrome: {
       // Optional: restrict to specific trading pairs
       // Set stable: true for correlated assets (e.g. USDC/USDT)
       marketAllowlist: [
         { assets: [USDC, ETH], stable: false },
         { assets: [USDC, WETH], stable: false, chainId: base.id },
       ],
       defaultSlippage: 0.005,
       maxSlippage: 0.5,
     },
   };
   

   Both

   actions.ts

   // Configure both providers — Actions will use them independently
   // based on the swap namespace's provider routing logic.
   // TODO: confirm best-price routing behavior across providers
   const swapConfig: SwapConfig = {
     uniswap: {
       marketAllowlist: [{ assets: [USDC, ETH] }],
     },
     velodrome: {
       marketAllowlist: [
         { assets: [USDC, ETH], stable: false },
       ],
     },
   };
   
9. Configure supported chains

   Configure supported chains:

   actions.ts

   // Additional config from previous steps...
   
   import { optimism, base } from "viem/chains";
   
   // Define any EVM chain
   const OPTIMISM = {
     chainId: optimism.id,
     rpcUrls: env.OPTIMISM_RPC_URL,
     bundler: {
       // Bundle and sponsor txs with a gas paymaster
       type: "simple" as const,
       url: env.OPTIMISM_BUNDLER_URL,
     },
   };
   
   const BASE = {
     chainId: base.id,
     rpcUrls: env.BASE_RPC_URL,
     bundler: {
       // Bundle and sponsor txs with a gas paymaster
       type: "simple" as const,
       url: env.BASE_BUNDLER_URL,
     },
   };
   
   const chains = [OPTIMISM, BASE];
   
10. Initialize Actions

    Finally bring it all together and initialize Actions:

    actions.ts

    // Additional config from previous steps...
    
    export const actions = createActions({
      wallet: walletConfig,
      assets: assetsConfig,
      lend: lendConfig,
      swap: swapConfig,
      chains,
    });
    
11. Take Action

    Once you’ve initialized your actions instance, import it anywhere you need to take action:

    import { actions } from './actions';
    
    // Use actions anywhere in your app
    const market = await actions.lend.getMarket({ ... });
    const wallet = await actions.wallet.createSmartWallet({ ... });
    const receipt = await wallet.lend.openPosition({ ... });
    
    // Swap tokens
    const swapReceipt = await wallet.swap.execute({
      amountIn: 100,
      assetIn: USDC,
      assetOut: ETH,
      chainId: base.id,
    });
    

Next Steps

For detailed API documentation and type definitions, see the Actions SDK Reference.