Guides

Quick Start

This guide is designed to allow users with basic notions of Typescript to interact with the AgoraStableSwap contract. The complete examples are available in this GitHub repository.

For this guide, we will be using the AUSD/CTK trading pair on the Ethereum Sepolia Testnet, where AUSD(AgoraDollar) is a proxy for our mainnet contract, and CTK (ConstantToken) serves as an example token that could be substituted with any other token in a mainnet pair.

Prerequisites

  • Node.js ≥ 18 and npm (preinstalled with Node).

  • TypeScript toolchain (optional but recommended):

    $npm install -D typescript ts-node @types/node
    $npx tsc --init

Package Installation

  • viem: a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with evm chains.
  • dotenv: a Node.js module that loads environment variables from a .env file, commonly used to manage configuration settings.

You can install these packages by running:

1npm install viem@^1 dotenv@^16

Wallet Setup

Never use production (mainnet) private keys or wallets when experimenting on testnets. Create a fresh, disposable wallet for Sepolia (or any other test network) so that mistakes or leaked keys can’t jeopardize real funds.

For the sake of simplicity, we recommend using MetaMask for this example because it makes switching between networks and exporting a private key straightforward. In production, you may want to use an MCP provider as an additional security precaution.

  1. Install MetaMask from the official site.
  2. Create a new wallet (or add an additional account).
  3. In MetaMask, switch the network to “Ethereum Sepolia Testnet” in the dropdown above your list of tokens.

If you don’t see it in this list, open the three line menu at the top right → select Networks → at the bottom make sure Show test networks is enabled → Choose Sepolia or use this information to setup the Sepolia network in MetaMask.

In order to sign transactions programmatically, you’ll need to export your private key from MetaMask into a .env file:

  1. Click the three-dot menu next to your account → Account Details → Private Key.
  2. Copy the value next to your Sepolia address.
  3. Paste it into a .env file and make sure .env is part of your .gitignore

Fund your test wallet

You’ll need a small amount of Sepolia ETH for gas. You can claim some from this faucet. Follow the instructions on this page and you’ll receive Sepolia ETH within seconds.

With your disposable wallet, environment variables, and testnet gas ready, you’re all set to create viem clients and run the code examples that follow.

Setting up a viem wallet client

For the rest of the guides we’ll use a single wallet client that can:

  1. Sign & send transactions (write calls)
  2. Perform public read calls (so we don’t need a separate public-only client)
  3. Automatically track nonces when you fire several transactions in quick succession

The pattern below satisfies all three goals.

We’ll use the sepolia client (Ethereum’s Testnet) for the following examples:

1import { http, createWalletClient, publicActions, nonceManager } from "viem";
2import { sepolia } from "viem/chains";
3import { privateKeyToAccount } from "viem/accounts";
4
5import dotenv from "dotenv";
6
7dotenv.config();
8if (!process.env.TESTNET_HOTWALLET_PK)
9		throw new Error('TESTNET_HOTWALLET_PK not set in .env');
10
11
12// Build the Account object from the test-only private key
13const account = privateKeyToAccount(
14		process.env.TESTNET_HOTWALLET_PK as `0x${string}`,
15		{ nonceManager }, // keeps nonces in sync across runs
16);
17
18// Create a wallet client and extend it with public-read helpers
19const client = createWalletClient({
20		chain: sepolia,
21		transport: http(
22			process.env.SEPOLIA_RPC_URL || 'https://ethereum-sepolia-rpc.publicnode.com',
23		),
24		account,
25}).extend(publicActions);

Using the client in scripts

Save the above code as walletClient.ts. You can now easily reuse this testnet client in other scripts. By following these steps:

  1. Be sure your new script is in the same folder as your walletClient.ts file.
  2. Add the following as the very first line of the script where you need the client:
1import { client } from "walletClient";

As stated above, our guides assume that you have already created the testnet wallet client. You will need to make sure to import it as described above before adding the example code.