Integration Guide

This docs give a brief about the how to integrate Epoch's API into your dapp

Overview

This guide covers the specific integration for Epoch Intents:

1. Creating task data using getTaskData()

2. Performing deposit and register intent in one operation using solveIntent()

Prerequisites

• Node.js >= 18

• Backend API endpoint -http://epoch.intents.dev.epochprotocol.xyz:3000

• Wallet connected via Viem

Installation

npm install @epoch-protocol/epoch-intents-sdk

Core Integration Pattern

1. Initialize the SDK

import { EpochIntentSDK } from '@epoch-intents/compact-sdk';
import { useWalletClient } from 'viem';

function MyComponent() {
  const { data: walletClient } = useWalletClient();
  const publicClient = usePublicClient();
  const { address } = useAccount();
  const chainId = useChainId();

  // Initialize SDK
  const epochSdk = new EpochIntentSDK({
    apiBaseUrl: '<endpoint>',
    walletClient: walletClient as any,
  });
}

2. Create Task Data

// Define your token swap parameters
const depositTokenAddress = '0xc04d2869665Be874881133943523723Be5782720';
const outputTokenAddress = '0x7946dd86eE310D0aC16804A37787289Fa5b88A8A';
const inputAmount = '1';
const outputAmount = '111';
const decimals = 18;

// Get task data from SDK
const { taskTypeString, intentData } = await epochSdk.getTaskData({
  taskType: TaskType.GetTokenOut,
  intentData: {
    isNative: false,
    depositTokenAddress,
    tokenInAmount: parseUnits(inputAmount || '0', decimals ?? 18).toString(),
    outputTokenAddress,
    minTokenOut: parseUnits(outputAmount || '0', decimals ?? 18).toString(),
    destinationChainId: chainId.toString(),
    protocolHashIdentifier: '0x0000000000000000000000000000000000000000000000000000000000000000',
    recipient: address as `0x${string}`,
  },
  // This is needed for the 
  // extraDataTypestring: 'uint256 somethingKey', // Optional
  // extraData: {
  //  somethingKey: '123',
  // },
});

console.log('taskTypeString:', taskTypeString);
console.log('intentData:', intentData);

3. Execute Deposit + Register Intent

// Execute the complete flow
const data = await epochSdk.solveIntent({
  isNative: false, // or true for native tokens
  sponsorAddress: address as `0x${string}`,
  taskTypeString,
  intentData,
});

console.log('Transaction result:', data);

API Reference

EpochIntentSDK.getTaskData()

Creates task data for token swap operations.

const { taskTypeString, intentData } = await epochSdk.getTaskData({
  taskType: TaskType.GetTokenOut,
  intentData: {
    isNative: boolean,
    depositTokenAddress: string,
    tokenInAmount: string,
    outputTokenAddress: string,
    minTokenOut: string,
    destinationChainId: string,
    protocolHashIdentifier: string,
    recipient: string,
  },
  extraDataTypestring?: string, // Optional: Additional type string for extra data
  extraData?: any, // Optional: Additional data fields
});

Parameters:

• taskType - Always TaskType.GetTokenOut for now

• intentData - Intent data object depending on the task type

• extraDataTypestring - (Optional) EIP-712 type string for additional data fields

• extraData - (Optional) Additional data fields to include in the intent

intentData for GetTokenOut Task -

• intentData.isNative - Whether depositing native tokens

• intentData.depositTokenAddress - Address of token to deposit

• intentData.tokenInAmount - Amount to deposit (as string, e.g., from parseUnits().toString())

• intentData.outputTokenAddress - Address of desired output token

• intentData.minTokenOut - Minimum amount expected out (as string, e.g., from parseUnits().toString())

• intentData.destinationChainId - Target chain ID (as string)

• intentData.protocolHashIdentifier - Protocol hash identifier (32-byte hex string)

• intentData.recipient - Recipient address for the output tokens

Returns:

• taskTypeString - EIP-712 type string for task data

• intentData - Task data object with token swap parameters

EpochIntentSDK.solveIntent()

Performs deposit and register intent in one operation. This method handles the complete flow: checking if deposit is needed, performing deposit and registration if required, and creating the allocation.

const result = await epochSdk.solveIntent({
  isNative: boolean,
  sponsorAddress: `0x${string}`,
  taskTypeString: string,
  intentData: object,
  sponsorSignature?: Hex, // Optional: Sponsor signature (generated if not provided)
});

Parameters:

• isNative - Whether depositing native tokens

• sponsorAddress - Address of the sponsor (user's wallet)

• taskTypeString - From getTaskData() result

• intentData - From getTaskData() result

• sponsorSignature - (Optional) Sponsor signature (will be generated if not provided)

Returns:

If deposit is required:

• depositResult - Transaction hash and receipt for deposit

• intentRequestData - The compact request data

• submittedIntentData - Intent hash, signature, and digest

• getIntentStatus - Current intent status

• retryIntentSolver - Function to retry intent solving

If deposit is not required:

• transactions - Array of execution transactions

Tokens Supported

USDC    0x2BB4FfD7E2c6D432b697554Efd77fA13bdbefd69   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
DAI     0xc30f1Ce05d1434d484E9A47283aA925fc8A8699a   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
USDT    0xc04d2869665Be874881133943523723Be5782720   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
WETH    0x7946dd86eE310D0aC16804A37787289Fa5b88A8A   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
WBTC    0x9b2a2754a9182fD65360E23afCDf3BeFF51796E9   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
PENGU   0xEA7dC9849206Ce73b11c465d37b85eC06B11Cf2C   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
OSWALD  0xB588418c0f90F07Bc9587d0050845a90C23C7502   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
KICK    0x512Ee6Bd7A4be5Ba4796F15Df080c4D0F89a38eD   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise
FERB    0x145e03A80c19ad1b9d0429d06b6d52707de724A0   18   Base, Optimism, Monad, Mainnet, Polygon, Tatara, Rise