Typescript SDK

Installation

To add the Renegade SDK to your project, install the required packages.

npm install @renegade-fi/node@latest @wagmi/core viem@2.x

This SDK is responsible for interacting with a relayer. Some actions, such as createWallet or deposit, require using your Ethereum wallet to sign messages or approve tokens. To perform these actions, we recommend using wagmi and viem.

Create Config

Create and export a new Renegade config using createConfig.

import { createConfig } from "@renegade-fi/node"
import { createPublicClient, http } from 'viem'
import { arbitrum } from 'viem/chains'
 
const viemClient = createPublicClient({ 
  chain: arbitrum,
  transport: http()
})

export const config = createConfig({
  darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518",
  priceReporterUrl: "mainnet.price-reporter.renegade.fi",
  relayerUrl: "mainnet.cluster0.renegade.fi",
  viemClient,
})

tip

Follow the instructions here to properly configure viemClient for either the Arbitrum One chain or the Arbitrum Sepolia chain, depending on which environment you want to use.

note

darkPoolAddress is the address of the darkpool proxy contract, not the implementation contract itself. You can find the darkpool proxy address for your environment here.

Use the SDK

Now, you can pass the config to use actions.

import { backOfQueueWallet } from "@renegade-fi/node"

const wallet = await getBackOfQueueWallet(config)

console.log("Wallet balances: ", wallet.balances)

Environment Setup

note

You must expose a TOKEN_MAPPING environment variable to use the SDK. You can do so by adding a .env file in the root of your project. See this repo for an example. You can find the token mapping for your environment here.

We recommend using Node v22 as it provides a WebSocket client to Node.js without external dependencies. If you are on a lower version of Node, you should provide your own WebSocket client, such as ws.

This SDK makes exclusive use of ES Modules. Check out this guide for more info on ESM support and Frequently Asked Questions across various tools and setups.

For Typescript configuration, check out this example repo for a reference tsconfig.json.

Protocol Core Concepts

Relayer

A relayer node is resposible for the matching and settlement of orders. Each individual relayer manages one or more wallets, meaning they are able to view the plaintext wallet but are unable to modify a wallet. In order to modify a wallet (placing orders, depositing assets, etc.), users sign updates to their wallet state and queue asynchronous “tasks” in the relayer.

note

Relayers manage task queues for each wallet, which means you do not necessarily need to wait for a task to complete before creating a new task. This is why two functions exist for fetching a wallet's state: getWalletFromRelayer (current wallet state) and getBackOfQueueWallet (wallet state after current task queue is cleared).

Wallet

A wallet is a data structure that contains a user's balances, orders, and keys. To create a wallet, you must sign a message using your Ethereum wallet to generate a derivation key. This derivation key is used to derive the required fields of a wallet, such as the keychain. Learn more about keychains here.

SDK Core Concepts

Config

The Config object is responsible for storing Renegade wallet state and internals. Most actions require a Config object to be passed as the first argument, as it contains the derivation key used to derive keys used to sign API requests and wallet updates.

Actions

This SDK exposes actions that are used to interact with a relayer, such as fetching a wallet's state or placing an order. Actions that access private wallet data require API authorization headers, which are automatically added for you when using the SDK. Browse the list of available actions below.

Types

This SDK provides types for various data structures used in the API.

Wallet: contains a user's balances, orders, and keys
Order: contains an order's parameters
Balance: contains the amount of an ERC-20 token a user has in addition to the fee amount owed for that token.
KeyChain: contains a user's key hierarchy as defined here.
OrderMetadata: contains useful metadata such as the order's ID, status, creation time, and PartialOrderFills since creation.
Task: contains a task's ID, status, type, and creation time.

Token

The Token class is used to store ERC-20 token metadata. It encapsulates information such as the token's address, name, decimals, and ticker symbol. This metadata is sourced from the TOKEN_MAPPING defined in your .env file.

Import

import { Token } from "@renegade-fi/node"

Properties

address: The address of the ERC-20 token.
name: The name of the token.
decimals: The number of decimals the token uses.
ticker: The ticker symbol of the token.

Static Methods

static findByTicker(ticker: string): Token

Returns

Token - The Token instance matching the given ticker.

Throws

Error - If no token with the given ticker is found in the TOKEN_MAPPING.

static findByAddress(address: `0x${string}`): Token

Returns

Token - The Token instance matching the given address.

Throws

Error - If no token with the given address is found in the TOKEN_MAPPING.

Usage

import { Token } from "@renegade-fi/node"

const usdc = Token.findByTicker("USDC")

console.log("USDC address: ", usdc.address)

const weth = Token.findByAddress("0xaf88d065e77c8cc2239327c5edb3a432268e5831")

console.log("WETH address: ", weth.address)

Configuration

createConfig

Import

import { createConfig } from "@renegade-fi/node"

Usage

import { createConfig } from "@renegade-fi/node"
import { createPublicClient, http } from 'viem'
import { arbitrum } from 'viem/chains'
 
const publicClient = createPublicClient({ 
  chain: arbitrum,
  transport: http()
})

export const config = createConfig({
  darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518",
  priceReporterUrl: "mainnet.price-reporter.renegade.fi",
  relayerUrl: "mainnet.cluster0.renegade.fi",
  viemClient: publicClient,
})

Parameters

darkPoolAddress
- 0x${string}
- The darkpool contract’s address.
priceReporterUrl
- string
- The price reporter’s URL.
relayerUrl
- string
- The relayer’s URL.
viemClient
- PublicClient
- Viem client used for wallet specific tasks e.g. signing a message.

Return Type

import { type Config } from '@renegade-fi/node'

Actions

createWallet

Action for starting a create wallet task on your connected relayer.

Import

import { createWallet } from "@renegade-fi/node"

Usage

import { createWallet, ROOT_KEY_MESSAGE_PREFIX } from "@renegade-fi/node"
import { privateKeyToAccount } from "viem/accounts"
import { arbitrum } from "viem/chains"
 
const account = privateKeyToAccount('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80') 

const seed = await account.signMessage({
  message: `${ROOT_KEY_MESSAGE_PREFIX} ${arbitrum.id}`,
})

config.setState((x) => ({ ...x, seed }))

await createWallet(config).then(() => console.log("Finished creating a wallet"))

Return Type

Promise<void>

Promise that resolves when the create wallet task has finished and the wallet has successfully been fetched from the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
a wallet with the same wallet ID already exists in the state of the connected relayer

lookupWallet

Action for starting a lookup wallet task on your connected relayer.

Import

import { lookupWallet } from "@renegade-fi/node"

Usage

import { lookupWallet } from "@renegade-fi/node"
import { arbitrum } from "viem/chains"
 
config.setState((x) => ({ ...x, seed }))

await lookupWallet(config).then(() => console.log('Finished looking up wallet'))

Return Type

Promise<void>

Promise that resolves when the lookup wallet task has finished and the wallet has successfully been fetched from the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
a wallet with the same wallet ID already exists in the state of the connected relayer
a wallet was not able to be found on-chain

getWalletFromRelayer

Action for fetching a wallet’s state from your connected relayer.

Import

import { getWalletFromRelayer } from "@renegade-fi/node"

Usage

const wallet = await getWalletFromRelayer(config)

console.log("Wallet balances: ", wallet.balances)

Return Type

Wallet

Error

An error may be thrown if:

a seed does not exist in the provided config
the wallet is not currently indexed by your connected relayer, in which case you should createWallet or lookupWallet
the API request authorization is incorrect / missing

getBackOfQueueWallet

Action for fetching the back of queue wallet state from your connected relayer.

note

Your connected relayer will manage a queue of tasks for you. By fetching the back of queue wallet, you are fetching your wallet state after all tasks in the queue have completed, which may not be the case. If a task fails, all subsequent tasks will transition to the Failed state and your queue will be cleared.

Import

import { getBackOfQueueWallet } from "@renegade-fi/node"

Usage

const wallet = await getBackOfQueueWallet(config)

console.log("Wallet balances: ", wallet.balances)

Return Type

Wallet

Error

An error may be thrown if:

a seed does not exist in the provided config
the wallet is not currently indexed by your connected relayer, in which case you should createWallet or lookupWallet
the API request authorization is incorrect / missing

deposit

Action for starting a deposit task on your connected relayer. Transfers ERC-20 tokens from your Arbitrum address to your Renegade wallet.

warning

You most likely want to use executeDeposit instead, as it will check for and execute ERC-20 allowances and permits as needed.

Import

import { deposit } from "@renegade-fi/node"

Usage

const { taskId } = await deposit(config, {
  fromAddr: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  mint: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  amount: BigInt(1000000),
  permitNonce: nonce,
  permitDeadline: deadline,
  permit: signature,
})

Parameters

fromAddr
- 0x${string}
- Account to transfer ERC-20 from.
mint
- 0x${string}
- ERC-20 contract address.
amount
- bigint
- Amount to deposit (should be multiplied by the number of decimals the ERC-20 supports)
permitNonce
- bigint
- A unique number, chosen by our app, to identify this permit. Once a permit is consumed, any other permit using that nonce will be invalid.
permitDeadline
- bigint
- The latest possible block timestamp for when this permit is valid.
permit
- 0x${string}
- The corresponding EIP-712 signature for the permit2 message, signed by owner. If the recovered address from signature verification does not match owner, the call will fail.

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the deposit task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided mint does not exist in the token mapping
the provided amount is less than the minimum transfer amount set by your connected relayer (currently 1 USDC)
the wallet update signature is incorrect / missing
the Permit2 permit is incorrect / missing
the API request authorization is incorrect / missing

executeDeposit

Action for starting a deposit task on your connected relayer, sending a transaction to approve the ERC-20 and signing a Permit2 permit if needed. Transfers ERC-20 tokens from your Arbitrum address to your Renegade wallet.

Import

import { executeDeposit } from "@renegade-fi/node"

Usage

import { createPublicClient, http } from "viem"
import { arbitrum } from "viem/chains"
import { createConfig as createWagmiConfig } from '@wagmi/core'

// Wagmi config
const viemConfig = createWagmiConfig({
  chains: [arbitrum],
  transports: {
    [arbitrum.id]: http(),
  },
})

const account = privateKeyToAccount('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80') 

const walletClient = createWalletClient({ 
  account, 
  chain: arbitrum,
  transport: http()
})

await executeDeposit(config, {
  mint: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  amount: BigInt(1000000),
  permit2Address: "0x000000000022D473030F116dDEE9F6B43aC78BA3",
  walletClient,
  viemConfig,
  awaitTask: true,
})

Parameters

mint
- 0x${string}
- ERC-20 contract address.
amount
- bigint
- Amount to deposit (should be multiplied by the number of decimals the ERC-20 supports)
permit2Address
- 0x${string}
- Permit2 contract address.
walletClient
- WalletClient
- viem Wallet Client used to sign messages.
viemConfig
- Config
- wagmi specific config for using wagmi actions
awaitTask
- boolean
- Whether or not to await task completion before resolving.

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the deposit task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided mint does not exist in the token mapping
the provided amount is less than the minimum transfer amount set by your connected relayer (currently 1 USDC)
the provided wallet client is not configured properly
the provided wagmi config is not configured properly
the API request authorization is incorrect / missing

withdraw

Action for starting a withdraw task on your connected relayer. Transfers ERC-20 tokens from your Renegade wallet to your Arbitrum address.

warning

You most likely want to use executeWithdrawal instead, as it will check for and pay fees if needed.

Import

import { payFees, withdraw } from "@renegade-fi/node"

Usage

import { payFees, withdraw } from "@renegade-fi/node"
await payFees(config)
await withdraw(config, {
  mint: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  amount: BigInt(1000000),
  destinationAddr: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
})

Parameters

destinationAddr
- 0x${string}
- Account to transfer ERC-20 to.
mint
- ERC-20 contract address.
amount
- bigint
- Amount to withdraw (must be multiplied by the number of decimals the ERC-20 supports)

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the withdraw task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided mint does not exist in the token mapping
the provided amount is less than the minimum transfer amount set by your connected relayer (currently 1 USDC)
there exist one or more balances with non-zero fees, meaning you must pay fees
the API request authorization is incorrect / missing

executeWithdrawal

Action for starting a withdraw task on your connected relayer, paying fees if needed. Transfers ERC-20 tokens from your Renegade wallet to your Arbitrum address.

Import

import { executeWithdrawal } from "@renegade-fi/node"

Usage

await executeWithdrawal(config, {
  destinationAddr: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  mint: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  amount: BigInt(1000000),
  awaitTask: true,
})

Parameters

destinationAddr
- 0x${string}
- Account to transfer ERC-20 to.
mint
- 0x${string}
- ERC-20 contract address.
amount
- bigint
- Amount to withdraw (should be multiplied by the number of decimals the ERC-20 supports)
awaitTask
- boolean
- Whether or not to await task completion before resolving.

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the withdraw task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided mint does not exist in the token mapping
the provided amount is less than the minimum transfer amount set by your connected relayer (currently 1 USDC)
the API request authorization is incorrect / missing

payFees

Action for starting necessary payFee task(s) on your connected relayer.

warning

You most likely will not invoke this function directly, as it is part of the executeWithdrawal function.

Import

import { payFees } from "@renegade-fi/node"

Usage

await payFees(config)

Return Type

Promise<{ taskIds: string[] }>

Promise that resolves to an array of IDs of payFee tasks in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the API request authorization is incorrect / missing

createOrder

Action for starting a place order task on your connected relayer.

Import

import { createOrder } from "@renegade-fi/node"

Usage

await createOrder(config, {
  base: "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
  quote: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  side: "buy",
  amount: BigInt(1000000000000000000),
  worstCasePrice: ((4000 * 1.5) * 10 ** (6 - 18)).toString() // For a buy order: maximum price of 6000 USDC per ETH
})

Parameters

base
- 0x${string}
- ERC-20 contract address of the base asset.
quote
- 0x${string}
- ERC-20 contract address of the quote asset (must be USDC).
side
- "buy" | "sell"
- The side this order is for
amount
- bigint
- Amount to place the order for (should be multiplied by the number of decimals the ERC-20 supports)
worstCasePrice (optional)
- string
- A number formatted as a string representing the worst case price that the order may be executed at. For buy side orders this is a maximum price, for sell side orders this is a minimum price.
- If no worst case price is provided, the action will fall back to setting default values (u64::MAX for buy side orders and 0 for sell side orders)
- Value should be decimal corrected according to the token pair (e.g. price * 10**(quoteDecimals - baseDecimals))

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the place order task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided base mint does not exist in the token mapping
the provided quote mint does not exist in the token mapping
the API request authorization is incorrect / missing

cancelOrder

Action for starting a cancel wallet task on your connected relayer.

Import

import { cancelOrder } from "@renegade-fi/node"

Usage

await cancelOrder(config, {
  id: "f801854d-b225-4855-926b-a24069446dfc",
})

Parameters

id
- string
- the ID of the order to cancel

Return Type

Promise<{ taskId: string }>

Promise that resolves to the ID of the cancel order task in the connected relayer.

Error

An error may be thrown if:

a seed does not exist in the provided config
the provided id mint does not exist in the wallet's list of orders
the API request authorization is incorrect / missing

Examples

Typescript SDK

Installation​

Create Config​

Use the SDK​

Environment Setup​

Protocol Core Concepts​

Relayer​

Wallet​

SDK Core Concepts​

Config​

Actions​

Types​

Token​

Configuration​

createConfig​

Actions​

createWallet​

lookupWallet​

getWalletFromRelayer​

getBackOfQueueWallet​

deposit​

executeDeposit​

withdraw​

executeWithdrawal​

payFees​

createOrder​

cancelOrder​

Examples​

Create a wallet​

Place an order​

Cancel an order​

Deposit​

Withdraw (Coming soon)​

Installation

Create Config

Use the SDK

Environment Setup

Protocol Core Concepts

Relayer

Wallet

SDK Core Concepts

Config

Actions

Types

Token

Configuration

createConfig

Actions

createWallet

lookupWallet

getWalletFromRelayer

getBackOfQueueWallet

deposit

executeDeposit

withdraw

executeWithdrawal

payFees

createOrder

cancelOrder

Examples

Create a wallet

Place an order

Cancel an order

Deposit

Withdraw (Coming soon)