gigabrain-agents

---
name: gigabrain-agents
description: Create, manage, and control Gigabrain autonomous trading agents on Hyperliquid. Use when the user wants to create trading bots, manage agent wallets, configure trading strategies, enable/disable agents, check agent execution history, or get strategy suggestions. Full lifecycle from strategy design to wallet management and execution monitoring.
license: MIT
compatibility: Requires GIGABRAIN_API_KEY environment variable. Get one at https://gigabrain.gg/profile?tab=api
metadata:
  author: gigabrain
  version: "1.0"
---

# Gigabrain Agents API

Create, manage, and control autonomous trading agents on Hyperliquid.

## Authentication

- Header: `Authorization: Bearer <GIGABRAIN_API_KEY>`
- Key format: `gb_sk_...`
- Get your key: https://gigabrain.gg/profile?tab=api

## Base URL

https://api.gigabrain.gg

## Endpoints

### Agent CRUD

#### POST /v1/agents - Create Agent
Create a new trading agent. Costs $0.20 in credits. Agent is created disabled by default.

```json
{
  "name": "string (required) - display name",
  "goal": "string (required) - trading goal, e.g. 'Monitor ETH/USDT and go long when RSI drops below 30'",
  "instructions": "string (required) - detailed strategy, behavior, and risk parameters",
  "triggers": [
    {
      "type": "scheduled",
      "cron": "*/15 * * * *"
    },
    {
      "type": "alpha",
      "match": "ETH momentum breakouts and trend reversals",
      "min_impact_rating": 3
    }
  ],
  "memory_enabled": true,
  "trading_enabled": false,
  "model": "default",
  "enabled": false
}
```

**Trigger types:**
- `scheduled` - cron-based. Supported: `*/5 * * * *` (5min), `*/15 * * * *` (15min), `0 * * * *` (hourly), `0 */4 * * *` (4h), `0 0 * * *` (daily). Minimum 5 minutes.
- `alpha` - signal-based. The `match` string is vector-matched against incoming alpha signals. `min_impact_rating` (1-5, default 3): 1-2 = low impact, 3 = moderate, 4 = high, 5 = critical.

#### GET /v1/agents - List Agents
List all agents owned by the authenticated user.
Query params: `limit` (integer, default 50)

#### GET /v1/agents/{agent_id} - Get Agent
Get details of a specific agent including configuration, triggers, stats, and status.

#### PATCH /v1/agents/{agent_id} - Update Agent
Update an agent's name, description, goal, or instructions. Only provided fields are updated.

```json
{
  "name": "optional new name",
  "description": "optional new description",
  "goal": "optional new goal",
  "instructions": "optional new instructions"
}
```

#### DELETE /v1/agents/{agent_id} - Delete Agent
Permanently delete an agent and all its data.
**WARNING: Export wallet keys and withdraw funds BEFORE deleting. This is irreversible.**

### Agent Lifecycle

#### POST /v1/agents/{agent_id}/enable - Enable Agent
Start the agent. It will begin executing on its configured triggers. Trading agents require a wallet to be generated and activated first.

#### POST /v1/agents/{agent_id}/disable - Disable Agent
Stop the agent. All trigger-based execution pauses. Configuration and history are preserved.

### Wallet Management

#### POST /v1/agents/{agent_id}/wallet - Generate Wallet
Generate a trading wallet for the agent. Returns the existing wallet if one has already been generated. Required before enabling a trading agent.

#### GET /v1/agents/{agent_id}/wallet - Get Wallet
Get wallet details including address, chain type, exchange, and status.

#### POST /v1/agents/{agent_id}/wallet/activate - Activate Wallet
Activate the wallet for live trading. The wallet must be funded first. Returns an error with deposit address if balance is insufficient.

#### POST /v1/agents/{agent_id}/wallet/send - Send Funds
Send funds from the agent's wallet to a destination address.

```json
{
  "destination": "0x... wallet address",
  "amount": 100.0
}
```

### Chat

#### POST /v1/agents/{agent_id}/chat - Chat with Agent
Send a message to an agent and get a response. Requires credits.

```json
{
  "message": "What positions are you currently monitoring?",
  "session_id": "optional - omit to start new session",
  "stream": false
}
```

### Monitoring

#### GET /v1/agents/{agent_id}/runs - Agent Runs
Get execution history for a specific agent, including trigger type, status, summary, reasoning, and whether an action was taken.
Query params: `limit` (integer, default 50)

### Strategy Suggestions

#### POST /v1/agents/suggest - Suggest Strategy
Get AI-generated trading strategy suggestions based on market context. Rate limited to 10 requests per hour.

```json
{
  "context": {
    "asset": "ETH",
    "style": "momentum",
    "risk_tolerance": "moderate",
    "timeframe": "4H"
  }
}
```

The `context` field is a free-form JSON object. Pass any key-value pairs for market context, preferences, or constraints. The body is optional.

## Rate Limits

- 60 requests per minute
- Strategy suggestions: 10 per hour
- Monitor `X-RateLimit-Remaining-Minute` header
- On 429 response: wait `Retry-After` seconds before retrying

## Agent Lifecycle Flow

The typical flow for creating and launching a trading agent:

1. **Create** - `POST /v1/agents` with name, goal, instructions, triggers
2. **Generate wallet** - `POST /v1/agents/{id}/wallet`
3. **Fund wallet** - Send USDC to the wallet address from `GET /v1/agents/{id}/wallet`
4. **Activate wallet** - `POST /v1/agents/{id}/wallet/activate`
5. **Enable agent** - `POST /v1/agents/{id}/enable`
6. **Monitor** - `GET /v1/agents/{id}/runs` to check execution history

To safely shut down:
1. **Disable** - `POST /v1/agents/{id}/disable`
2. **Export keys** - Export private key from the Gigabrain UI (Profile → Agents → Export Key)
3. **Withdraw funds** - `POST /v1/agents/{id}/wallet/send`
4. **Delete** - `DELETE /v1/agents/{id}`

## Error Handling

- 401: Invalid or revoked API key - verify at https://gigabrain.gg/profile?tab=api
- 404: Agent not found - check the agent_id
- 429: Rate limit exceeded - wait `Retry-After` seconds
- 500/503: Server error - retry with exponential backoff

## Important Notes

- Agents are created disabled by default - call enable after wallet setup
- Trading agents MUST have a generated and activated wallet before enabling
- ALWAYS export wallet keys and withdraw funds before deleting an agent. Deletion is permanent and funds are irrecoverable
- Each agent gets its own dedicated Hyperliquid wallet
- Agent creation costs $0.20 in credits; chat and runs also consume credits

Create a Gigabrain trading agent called "ETH Momentum Bot" that monitors
ETH/USDT and goes long when RSI drops below 30 on the 4H chart. Use a
scheduled trigger every 15 minutes. Enable trading and set up the wallet.

Safely shut down my agent "ETH Momentum Bot". Disable it, export the
wallet keys, withdraw all funds to 0xYourAddress, then delete it.