Paradex SDK

Official JavaScript/TypeScript SDK for Paradex - a decentralized perpetuals exchange built on Starknet.

Installation

npm install @paradex/sdk

yarn add @paradex/sdk

pnpm add @paradex/sdk

Quick Start

Browser (MetaMask/Web3 Wallet)

import * as Paradex from '@paradex/sdk';
import { ethers } from 'ethers';

// 1. Fetch configuration for your environment
const config = await Paradex.Config.fetch('testnet'); // or 'mainnet'

// 2. Connect to user's wallet
const provider = new ethers.BrowserProvider(window.ethereum);
const ethersSigner = await provider.getSigner();
const signer = Paradex.Signer.fromEthers(ethersSigner);

// 3. Create Paradex client
const client = await Paradex.Client.fromEthSigner({ config, signer });

// 4. Use the client
console.log('Your Paradex address:', client.getAddress());
const balance = await client.getTokenBalance('USDC');
console.log('USDC Balance:', balance.size);

Node.js (Private Key)

import * as Paradex from '@paradex/sdk';
import { ethers } from 'ethers';

// 1. Fetch configuration
const config = await Paradex.Config.fetch('testnet');

// 2. Create wallet from private key
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
const signer = Paradex.Signer.fromEthers(wallet);

// 3. Create Paradex client
const client = await Paradex.Client.fromEthSigner({ config, signer });

// 4. Use the client
const balance = await client.getTokenBalance('USDC');
console.log('Balance:', balance.size);

Core Concepts

Client

The ParadexClient is the main interface for interacting with Paradex. It handles authentication and provides a clean API for common operations.

// Create from Ethereum wallet
const client = await Paradex.Client.fromEthSigner({ config, signer });

// Create from Starknet account
const client = await Paradex.Client.fromStarknetAccount({
  config,
  account: starknetAccount,
  starknetProvider: optionalProvider,
});

Configuration

Fetch environment-specific configuration:

const config = await Paradex.Config.fetch('testnet'); // testnet, mainnet, or custom URL

Common Operations

Get Token Balance

const balance = await client.getTokenBalance('USDC');
console.log(`Balance: ${balance.size} USDC`);

Get Maximum Withdrawable Amount

const maxWithdraw = await client.getMaxWithdraw('USDC');
console.log(`Max withdrawable: ${maxWithdraw.amount} USDC`);
console.log(`Chain amount: ${maxWithdraw.amountChain}`);

Check Socialized Loss Factor

const { socializedLossFactor } = await client.getSocializedLossFactor();
if (Number(socializedLossFactor) > 0) {
  console.warn('Socialized loss is active');
}

Calculate Receivable Amount

const receivable = await client.getReceivableAmount('USDC', '100');
console.log(`Requesting: 100 USDC`);
console.log(`Will receive: ${receivable.receivableAmount} USDC`);
console.log(`Loss factor: ${receivable.socializedLossFactor}`);

Withdraw Tokens

// Simple withdrawal (no bridge call)
const result = await client.withdraw('USDC', '50', []);
console.log('Transaction hash:', result.hash);

// Wait for confirmation
await client.waitForTransaction(result.hash);
console.log('Withdrawal complete!');

Withdraw with Bridge Call

// Calculate receivable amount first
const receivable = await client.getReceivableAmount('USDC', '100');

// Prepare bridge call with receivable amount
const bridgeCall = {
  contractAddress: '0x...',
  entrypoint: 'deposit',
  calldata: ['...', receivable.receivableAmountChain],
};

// Execute withdrawal with bridge call
const result = await client.withdraw('USDC', '100', bridgeCall);
await client.waitForTransaction(result.hash);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions out of the box.

import type {
  MaxWithdraw,
  ParadexClient,
  ParadexConfig,
  ReceivableAmount,
  TokenBalance,
  WithdrawResult,
} from '@paradex/sdk';

// All types are fully typed and autocomplete-friendly
const balance: TokenBalance = await client.getTokenBalance('USDC');

Error Handling

try {
  const balance = await client.getTokenBalance('USDC');
  console.log('Balance:', balance.size);
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to get balance:', error.message);
  }
}

Advanced Usage

Access Underlying Provider

const provider = client.getProvider();
// Access the authenticated RPC provider for advanced operations

Get Account Address

const address = client.getAddress();
console.log('Your Paradex address:', address);

Custom RPC Calls

const provider = client.getProvider();
const result = await provider.callContract({
  contractAddress: '0x...',
  entrypoint: 'get_balance',
  calldata: ['0x123'],
});

Best Practices

1. Environment Variables

Store sensitive data in environment variables:

const privateKey = process.env.PRIVATE_KEY;
if (!privateKey) {
  throw new Error('PRIVATE_KEY environment variable is required');
}

2. Error Handling

Always wrap SDK calls in try-catch blocks:

try {
  const client = await Paradex.Client.fromEthSigner({ config, signer });
  const balance = await client.getTokenBalance('USDC');
} catch (error) {
  // Handle errors appropriately
  console.error('SDK Error:', error);
}

3. Socialized Loss Checks

Always check for socialized loss before withdrawals:

const receivable = await client.getReceivableAmount('USDC', amount);
if (Number(receivable.socializedLossFactor) !== 0) {
  // Warn user they will receive less than requested
  console.warn(
    `Due to socialized loss, you will receive ${receivable.receivableAmount} instead of ${amount}`,
  );
}

4. Transaction Confirmations

Wait for transaction confirmations:

const result = await client.withdraw('USDC', '100', []);
console.log('Transaction submitted:', result.hash);

// Wait for confirmation
await client.waitForTransaction(result.hash);
console.log('Transaction confirmed!');

5. Type Safety

Leverage TypeScript for type safety:

import type { ParadexClient } from '@paradex/sdk';

function processBalance(client: ParadexClient, token: string): Promise<void> {
  // TypeScript will ensure correct usage
  return client.getTokenBalance(token).then((balance) => {
    console.log(`${token} Balance:`, balance.size);
  });
}

Browser Usage Notes

To use the Paradex SDK in the browser, you'll need to configure your bundler to polyfill Node.js modules:

Webpack 5

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      buffer: require.resolve('buffer/'),
      crypto: require.resolve('crypto-browserify'),
      stream: require.resolve('stream-browserify'),
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser',
    }),
  ],
};

Vite

// vite.config.js
import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [nodePolyfills()],
  define: {
    'process.env.NODE_DEBUG': JSON.stringify(''),
  },
});

Examples

See the examples directory for complete working examples:

• account-ethereum.ts - Create client from Ethereum wallet
• account-starknet.ts - Create client from Starknet account
• withdrawal-node.ts - Complete withdrawal flow (Node.js)
• withdrawal.ts - Complete withdrawal flow (Browser)

For a full React application example, see: paradex-react-example

API Reference

Client Methods

| Method | Description | Returns | | ------------------------------------- | -------------------------------------- | ---------------------- | | getTokenBalance(token) | Get token balance | TokenBalance | | getMaxWithdraw(token) | Get maximum withdrawable amount | MaxWithdraw | | getSocializedLossFactor() | Get current socialized loss factor | SocializedLossFactor | | getReceivableAmount(token, amount) | Calculate amount after socialized loss | ReceivableAmount | | withdraw(token, amount, bridgeCall) | Initiate withdrawal | WithdrawResult | | waitForTransaction(hash, options?) | Wait for transaction confirmation | TransactionReceipt | | getAddress() | Get account address | string | | getProvider() | Get underlying provider | DefaultProvider |

Configuration

| Method | Description | Returns | | ------------------- | ----------------------------------- | --------------- | | Config.fetch(env) | Fetch configuration for environment | ParadexConfig |

Signer

| Method | Description | Returns | | --------------------------- | ---------------------------- | ---------------- | | Signer.fromEthers(signer) | Create signer from ethers.js | EthereumSigner |

Support

• Discord: Join our Discord
• Documentation: docs.paradex.trade
• Issues: GitHub Issues

License

MIT

Warning

⚠️ This SDK is in active development. APIs may change between versions. Please check the changelog before upgrading.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.