n8n-nodes-dex/README.md

n8n node module for dYdX v4 trading and account access

# n8n-nodes-dydx

This is an n8n community node. It lets you use dYdX v4 in your n8n workflows.

dYdX v4 is a decentralized perpetual futures exchange on the Cosmos blockchain that allows users to trade cryptocurrencies with leverage.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

[Installation](#installation)  
[Operations](#operations)  
[Credentials](#credentials)  
[Compatibility](#compatibility)  
[Resources](#resources)  
[Code Structure](#code-structure)  

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

### npm
```bash
npm install n8n-nodes-dydx
```

### n8n Community Nodes
1. Go to **Settings > Community Nodes**
2. Click on **Install**
3. Enter `n8n-nodes-dydx` in **Enter npm package name**
4. Agree to the risks of using community nodes
5. Click on **Install**

After successful installation, you can start using the dYdX node in your n8n workflows!

## Code Structure

The project follows a modular architecture with the following main components:

- `Dydx`: Main n8n node implementation
- `AccountService`: Handles account-related operations (subaccounts, positions, etc.)
- `TradingService`: Manages trading operations (orders, transfers, etc.)
- `DydxApi`: Credentials management for dYdX API access

## Command Line Tools

This package includes TypeScript tools for interacting with dYdX without needing to set up n8n:

### Using the Query Tool

The simplest way to query dYdX account data:

```bash
# Using npm script
npm run query -- --address=<your_address> --network=<mainnet|testnet>

# Or directly with ts-node
npx ts-node dydx-query.ts --address=<your_address> --network=<mainnet|testnet>
```

Example:
```bash
npm run query -- --address={ADDRESS} --network=mainnet
```

This query tool:
1. Connects directly to the dYdX API
2. Retrieves subaccount information for the provided address
3. Displays account equity and open positions

### Using the Full CLI (Development)

For more comprehensive testing with position data:

```bash
npm run cli -- --address=<your_address> --network=<mainnet|testnet> [--positions=true]
```

### Parameters

- `--address`: (Required) The dYdX account address to query
- `--network`: (Optional) Network to connect to - either `mainnet` or `testnet` (default: `testnet`)

## Operations

- **List Subaccounts**: Get all subaccounts for the authenticated user
- **Get Subaccount**: Get details for a specific subaccount
- **Get Account Equity**: Get equity for a specific subaccount
- **Transfer Between Subaccounts**: Transfer funds between subaccounts
- **Place Order**: Place a limit order on the dYdX exchange
- **Cancel Order**: Cancel an existing order on the dYdX exchange
- **Smart Position**: Intelligently achieve target position size by placing and adjusting orders
- **List Positions**: Get all open positions for the authenticated user
- **Get Balance**: Get account balances
- **Market Spread**: Get best bid and ask prices for a market

## Credentials

You need the following information to authenticate with dYdX:

- **Mnemonic**: Your wallet mnemonic (seed phrase)
- **Address**: Your wallet address
- **Network**: Select either testnet or mainnet

## Compatibility

This node was developed for n8n version 1.0 and above. It was tested with version 1.0.0.

## Resources

* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
* [dYdX v4 Documentation](https://dydxprotocol.github.io/v4-documentation/)
* [dYdX v4 client JS](https://github.com/dydxprotocol/v4-client-js)