Official JavaScript/TypeScript SDK for Paradex - a decentralized perpetuals exchange built on Starknet.
npm install @paradex/sdkyarn add @paradex/sdkpnpm add @paradex/sdkimport * 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);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);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,
});Fetch environment-specific configuration:
const config = await Paradex.Config.fetch('testnet'); // testnet, mainnet, or custom URLconst balance = await client.getTokenBalance('USDC');
console.log(`Balance: ${balance.size} USDC`);const maxWithdraw = await client.getMaxWithdraw('USDC');
console.log(`Max withdrawable: ${maxWithdraw.amount} USDC`);
console.log(`Chain amount: ${maxWithdraw.amountChain}`);const { socializedLossFactor } = await client.getSocializedLossFactor();
if (Number(socializedLossFactor) > 0) {
console.warn('Socialized loss is active');
}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}`);// 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!');// 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);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');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);
}
}const provider = client.getProvider();
// Access the authenticated RPC provider for advanced operationsconst address = client.getAddress();
console.log('Your Paradex address:', address);const provider = client.getProvider();
const result = await provider.callContract({
contractAddress: '0x...',
entrypoint: 'get_balance',
calldata: ['0x123'],
});Store sensitive data in environment variables:
const privateKey = process.env.PRIVATE_KEY;
if (!privateKey) {
throw new Error('PRIVATE_KEY environment variable is required');
}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);
}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}`,
);
}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!');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);
});
}To use the Paradex SDK in the browser, you'll need to configure your bundler to polyfill Node.js modules:
// 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.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(''),
},
});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
| 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 |
| Method | Description | Returns |
|---|---|---|
Config.fetch(env) |
Fetch configuration for environment | ParadexConfig |
| Method | Description | Returns |
|---|---|---|
Signer.fromEthers(signer) |
Create signer from ethers.js | EthereumSigner |
- Discord: Join our Discord
- Documentation: docs.paradex.trade
- Issues: GitHub Issues
MIT
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.