Skip to content

Commit eeb6893

Browse files
Sumeet ChouguleSumeet Chougule
Sumeet Chougule
authored and
Sumeet Chougule
committed
Add Hummingbot plugin for market making
This commit adds a new plugin that integrates Hummingbot's market making capabilities with Eliza trading agents. The plugin provides: - Real-time market data streaming - Simple market making strategy with configurable parameters - Order lifecycle management - Inventory skew management
1 parent ec741a5 commit eeb6893

13 files changed

+1507
-0
lines changed

‎packages/plugin-hummingbot/README.md

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Hummingbot Plugin for Eliza
2+
3+
A powerful plugin that integrates Hummingbot's market making capabilities with Eliza trading agents. This plugin enables Eliza to perform automated market making and trading operations using Hummingbot's infrastructure.
4+
5+
## Features
6+
7+
- Real-time market data streaming via WebSocket
8+
- Simple market making strategy with configurable parameters
9+
- Inventory skew management
10+
- Order lifecycle management (create, cancel, track)
11+
- Rate limiting and error handling
12+
- Automatic reconnection and recovery
13+
- Multi-level order book support
14+
15+
## Installation
16+
17+
```bash
18+
npm install @eliza/plugin-hummingbot
19+
```
20+
21+
## Usage in Eliza Character
22+
23+
Add the plugin to your character configuration:
24+
25+
```json
26+
{
27+
"plugins": ["@eliza/plugin-hummingbot"],
28+
"settings": {
29+
"HUMMINGBOT_CONFIG": {
30+
"instance": {
31+
"url": "http://localhost:15888",
32+
"wsUrl": "ws://localhost:8060",
33+
"apiKey": "your-hummingbot-api-key",
34+
"instanceId": "eli-agent"
35+
},
36+
"defaultStrategy": {
37+
"exchange": "binance",
38+
"tradingPair": "BTC-USDT",
39+
"orderAmount": 0.001,
40+
"orderLevels": 2,
41+
"maxOrderAge": 1800,
42+
"inventorySkewEnabled": true,
43+
"inventoryTargetBase": 50,
44+
"bidSpread": 0.2,
45+
"askSpread": 0.2,
46+
"minSpread": 0.1,
47+
"maxSpread": 0.5,
48+
"priceSource": "current_market",
49+
"orderRefreshTime": 60
50+
}
51+
}
52+
}
53+
}
54+
```
55+
56+
> **Note:** The `url` and `apiKey` fields in the instance configuration are required. The plugin will throw an error if either of these values is missing or undefined.
57+
58+
## Quick Start
59+
60+
```typescript
61+
import { HummingbotPlugin } from '@eliza/plugin-hummingbot';
62+
import { SimpleMarketMaking } from '@eliza/plugin-hummingbot/strategies';
63+
64+
// Initialize the plugin
65+
const plugin = new HummingbotPlugin({
66+
instance: {
67+
url: 'http://localhost:15888', // Default Hummingbot REST API port
68+
wsUrl: 'ws://localhost:8060', // Default Hummingbot WebSocket port
69+
apiKey: 'your-api-key',
70+
instanceId: 'instance-1'
71+
}
72+
});
73+
74+
// Initialize plugin
75+
await plugin.init();
76+
77+
// Configure market making strategy
78+
const config = {
79+
exchange: "binance",
80+
tradingPair: "BTC-USDT",
81+
orderAmount: 0.001, // Base order size in BTC
82+
orderLevels: 2, // Number of orders on each side
83+
maxOrderAge: 1800, // Maximum order age in seconds
84+
inventorySkewEnabled: true,
85+
inventoryTargetBase: 50, // Target base asset percentage
86+
inventoryRangeMultiplier: 1.5,
87+
bidSpread: 0.2, // 0.2% spread for bids
88+
askSpread: 0.2, // 0.2% spread for asks
89+
minSpread: 0.1, // Minimum allowed spread
90+
maxSpread: 0.5, // Maximum allowed spread
91+
priceSource: 'current_market',
92+
minimumSpreadEnabled: true,
93+
pingPongEnabled: false,
94+
orderRefreshTime: 60 // Refresh orders every 60 seconds
95+
};
96+
97+
// Create and start the strategy
98+
const strategy = new SimpleMarketMaking(plugin, config);
99+
const stopStrategy = await strategy.start();
100+
101+
// Handle shutdown gracefully
102+
process.on('SIGINT', async () => {
103+
console.log('Shutting down strategy...');
104+
await stopStrategy();
105+
process.exit(0);
106+
});
107+
```
108+
109+
## Configuration Guide
110+
111+
### Plugin Configuration
112+
113+
| Parameter | Type | Description | Required |
114+
|-----------|--------|-------------|----------|
115+
| url | string | Hummingbot REST API URL | Yes |
116+
| wsUrl | string | Hummingbot WebSocket URL | Yes |
117+
| apiKey | string | API key for authentication | Yes |
118+
| instanceId| string | Unique identifier for the instance | Yes |
119+
120+
### Market Making Strategy Configuration
121+
122+
| Parameter | Type | Description | Required | Default |
123+
|-----------|------|-------------|----------|---------|
124+
| exchange | string | Exchange to trade on | Yes | - |
125+
| tradingPair | string | Trading pair (e.g., "BTC-USDT") | Yes | - |
126+
| orderAmount | number | Base order size | Yes | - |
127+
| orderLevels | number | Number of orders on each side | No | 1 |
128+
| maxOrderAge | number | Maximum order age in seconds | No | 1800 |
129+
| inventorySkewEnabled | boolean | Enable inventory skew | No | false |
130+
| inventoryTargetBase | number | Target base asset % | No | 50 |
131+
| bidSpread | number | Bid spread percentage | Yes | - |
132+
| askSpread | number | Ask spread percentage | Yes | - |
133+
| minSpread | number | Minimum spread percentage | No | 0.1 |
134+
| maxSpread | number | Maximum spread percentage | No | 0.5 |
135+
| priceSource | string | Price source for orders | No | 'current_market' |
136+
| orderRefreshTime | number | Order refresh interval (seconds) | No | 60 |
137+
138+
## API Reference
139+
140+
### HummingbotPlugin
141+
142+
#### Methods
143+
144+
- `init(): Promise<void>` - Initialize the plugin
145+
- `subscribeToMarketData(exchange: string, symbol: string, callback: (data: MarketData) => void): Promise<() => void>` - Subscribe to market data
146+
- `placeOrder(params: OrderParams): Promise<string>` - Place a new order
147+
- `cancelOrder(exchange: string, orderId: string): Promise<boolean>` - Cancel an order
148+
- `getOrderStatus(exchange: string, orderId: string): Promise<any>` - Get order status
149+
150+
### SimpleMarketMaking Strategy
151+
152+
#### Methods
153+
154+
- `start(): Promise<() => void>` - Start the market making strategy
155+
- `updateBalances(): Promise<void>` - Update portfolio balances
156+
- `cancelAllOrders(): Promise<void>` - Cancel all active orders
157+
158+
## Error Handling
159+
160+
The plugin implements comprehensive error handling:
161+
162+
- Rate limit handling with automatic retries
163+
- WebSocket connection management with automatic reconnection
164+
- Order validation and error reporting
165+
- Balance checking before order placement
166+
167+
## Prerequisites
168+
169+
- Running Hummingbot instance
170+
- Valid API credentials
171+
- Sufficient balance on the target exchange

‎packages/plugin-hummingbot/jest.config.js

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/** @type {import('ts-jest').JestConfigWithTsJest} */
2+
module.exports = {
3+
preset: 'ts-jest',
4+
testEnvironment: 'node',
5+
roots: ['<rootDir>/src'],
6+
testMatch: ['**/__tests__/**/*.test.ts'],
7+
moduleNameMapper: {
8+
'^@/(.*)$': '<rootDir>/src/$1',
9+
},
10+
};

‎packages/plugin-hummingbot/package.json

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "@eliza/plugin-hummingbot",
3+
"version": "0.1.0",
4+
"description": "Hummingbot integration for Eliza trading agents",
5+
"main": "dist/index.js",
6+
"types": "dist/index.d.ts",
7+
"scripts": {
8+
"build": "tsc",
9+
"prepublishOnly": "pnpm run build",
10+
"test": "jest",
11+
"test:watch": "jest --watch"
12+
},
13+
"publishConfig": {
14+
"access": "public"
15+
},
16+
"keywords": [
17+
"eliza",
18+
"plugin",
19+
"hummingbot",
20+
"trading",
21+
"market-making",
22+
"cryptocurrency"
23+
],
24+
"author": "Nethermind",
25+
"license": "MIT",
26+
"dependencies": {
27+
"@ai16z/eliza": "workspace:*",
28+
"axios": "^1.6.0",
29+
"ws": "^8.16.0"
30+
},
31+
"devDependencies": {
32+
"@types/jest": "^29.5.11",
33+
"@types/ws": "^8.5.10",
34+
"jest": "^29.7.0",
35+
"ts-jest": "^29.1.1",
36+
"typescript": "^5.0.0"
37+
},
38+
"peerDependencies": {
39+
"@ai16z/eliza": "*"
40+
}
41+
}

‎packages/plugin-hummingbot/src/actions/market-making.ts

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import { HummingbotPlugin } from '..';
2+
import { SimpleMarketMaking } from '../strategies/simple-market-making';
3+
import { MarketMakingConfig } from '../types';
4+
5+
export async function startMarketMaking(
6+
plugin: HummingbotPlugin,
7+
config: MarketMakingConfig
8+
): Promise<() => Promise<void>> {
9+
const strategy = new SimpleMarketMaking(plugin, config);
10+
return strategy.start();
11+
}
12+
13+
export async function stopMarketMaking(
14+
plugin: HummingbotPlugin,
15+
strategyId: string
16+
): Promise<void> {
17+
await plugin.stopStrategy(strategyId);
18+
}
19+
20+
export async function getMarketMakingStatus(
21+
plugin: HummingbotPlugin,
22+
strategyId: string
23+
): Promise<any> {
24+
return plugin.getStrategyStatus(strategyId);
25+
}

‎packages/plugin-hummingbot/src/actions/orders.ts

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { HummingbotPlugin } from '..';
2+
import { OrderParams } from '../types';
3+
4+
export async function placeOrder(
5+
plugin: HummingbotPlugin,
6+
params: OrderParams
7+
): Promise<string> {
8+
return plugin.orderService.placeOrder(params);
9+
}
10+
11+
export async function cancelOrder(
12+
plugin: HummingbotPlugin,
13+
exchange: string,
14+
orderId: string
15+
): Promise<boolean> {
16+
return plugin.orderService.cancelOrder(exchange, orderId);
17+
}
18+
19+
export async function cancelAllOrders(
20+
plugin: HummingbotPlugin,
21+
exchange: string
22+
): Promise<void> {
23+
await plugin.orderService.cancelAllOrders(exchange);
24+
}

0 commit comments

Comments
 (0)