Quick Start

From zero to token launch in 3 API calls. In production, include x-api-key on every request.

curl -X POST /api/agent/wallet \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{}'

# Response:
# { "address": "0xABC...", "privateKey": "0xDEF...", "balance": "0" }

curl -X POST /api/agent/create-token \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{
    "privateKey": "0xYOUR_KEY",
    "name": "MyToken",
    "symbol": "MTK",
    "description": "An agent-launched token",
    "creatorFeeBps": 40
  }'

# Response:
# { "success": true, "tokenAddress": "0x...", "creatorFeeBps": 40 }

How It Works

Note: platform (0.6%) and creator (0.4%) fees are fixed. Creation/graduation fees are on-chain values (defaults shown above).

In-App Assistant

hyperclaw AI (on the home page) can search tokens, quote trades, check balances, and prepare buy/sell/launch actions. Trades require a wallet confirmation. Token launches are executed by a relayer (gasless) and go live immediately. In production, wallet tools require login.

GET /skills.md

Twitter Bot

@hypeclawlive runs as a separate worker process. It polls mentions and replies using the same agent tools as the in-app chat.

npm run twitter-bot

Agent Discovery

hyperclaw supports multiple agent discovery standards. Point your agent at any of these files.

Authentication

There are two layers of auth:

• x-api-key header: required when the server is configured with AGENT_API_KEY (always in production).
• Wallet key: write endpoints include an EVM privateKey in the JSON body to sign transactions.

# Server auth (prod):
-H "x-api-key: $HYPERPUMP_API_KEY"

# Optional network selector:
-H "x-hyperpump-network: mainnet"   # or "fork"

# Writes (create, buy, sell, graduate) sign with a wallet key:
{ "privateKey": "0xYOUR_PRIVATE_KEY", ...params }

# Reads (tokens, quote, wallet balance) do not need privateKey:
GET /api/agent/tokens?offset=0&limit=20

API Reference

Wallet

{}

{
  "address": "0xABC...",
  "privateKey": "0xDEF...",
  "balance": "0",
  "balanceWei": "0",
  "warning": "Store your private key securely. It will not be shown again."
}

{ "privateKey": "0xYOUR_PRIVATE_KEY" }

{
  "address": "0xABC...",
  "balance": "100.5",
  "balanceWei": "100500000000000000000"
}

{
  "address": "0xABC...",
  "balance": "100.5",
  "balanceWei": "100500000000000000000"
}

Tokens

{
  "success": true,
  "txHash": "0x...",
  "tokenAddress": "0xNEW_TOKEN",
  "creator": "0xYOUR_ADDRESS",
  "name": "MyToken",
  "symbol": "MTK",
  "image": "Qm... (or url)",
  "creatorFeeBps": 40,
  "gasUsed": "300000"
}

{
  "tokens": [
    {
      "address": "0x...",
      "name": "MyToken",
      "symbol": "MTK",
      "price": "0.00000000003177",
      "progressPercent": 3.96,
      "graduated": false,
      "creatorFeeBps": 40
    }
  ],
  "total": 12,
  "offset": 0,
  "limit": 20
}

{
  "address": "0x...",
  "name": "MyToken",
  "symbol": "MTK",
  "price": "0.00000000003177",
  "marketCap": "31.77",
  "progressPercent": 3.96,
  "graduated": false,
  "creatorFeeBps": 40,
  "creatorFeePercent": 0.4,
  "holderBalance": "1000000.0"
}

Graduation

{
  "success": true,
  "txHash": "0x...",
  "token": "0x...",
  "pair": "0x... (dex pair)",
  "hypeInLP": "50.0",
  "tokensInLP": "123456789.0",
  "gasUsed": "120000"
}

Trading

{ "side": "buy", "hypeIn": "5", "tokensOut": "151969957.08" }

{ "side": "sell", "tokensIn": "50000000", "hypeOut": "1.625" }

{
  "success": true,
  "txHash": "0x...",
  "token": "0x...",
  "hypeSpent": "5",
  "tokensReceived": "151969957.08",
  "protocolFee": "0.03",
  "creatorFee": "0.02",
  "graduated": false,
  "graduationReady": false,
  "gasUsed": "95000"
}

{
  "success": true,
  "txHash": "0x...",
  "token": "0x...",
  "tokensSold": "50000000",
  "hypeReceived": "1.625",
  "hypeOutGross": "1.6414",
  "protocolFee": "0.0098",
  "creatorFee": "0.0066",
  "gasUsed": "84000"
}

Analytics

{
  "token": "0x...",
  "totalVolume": "123.45",
  "buyVolume": "80.12",
  "sellVolume": "43.33",
  "tradeCount": 420,
  "uniqueTraders": 1337,
  "priceHistory": [{ "timestamp": 1710000000, "price": "0.000000030000000000" }],
  "graduationTimestamp": null
}

{
  "token": "0x...",
  "items": [
    { "type": "trade", "data": { "isBuy": true, "hypeAmount": "1000000000000000000", "tokenAmount": "..." } }
  ]
}

{
  "token": "0x...",
  "totalHolders": 1234,
  "holders": [{ "holder": "0x...", "balance": "1000000000000000000", "pct": "0.10%" }]
}

Code Examples

Python — Launch + Buy

import requests
import os

BASE = "https://hyperclaw.xyz/api/agent"
HEADERS = {
    "x-api-key": os.environ["HYPERPUMP_API_KEY"],
    "x-hyperpump-network": "mainnet",
}

# 1. Create wallet
wallet = requests.post(f"{BASE}/wallet", json={}, headers=HEADERS).json()
pk = wallet["privateKey"]
print(f"Address: {wallet['address']}")

# 2. Fund wallet with HYPE (manual step)

# 3. Launch token with 0.4% creator fee (fixed)
token = requests.post(f"{BASE}/create-token", json={
    "privateKey": pk,
    "name": "AgentCoin",
    "symbol": "AGENT",
    "description": "Launched by an AI agent",
    "creatorFeeBps": 40
}, headers=HEADERS).json()
print(f"Token: {token['tokenAddress']}")

# 4. Buy 5 HYPE worth
buy = requests.post(f"{BASE}/buy", json={
    "privateKey": pk,
    "token": token["tokenAddress"],
    "amountHype": "5",
    "slippageBps": 200
}, headers=HEADERS).json()
print(f"Got {buy['tokensReceived']} tokens")

JavaScript / TypeScript

const BASE = "https://hyperclaw.xyz/api/agent";
const API_KEY = process.env.HYPERPUMP_API_KEY;
const NETWORK = "mainnet";
if (!API_KEY) throw new Error("Missing HYPERPUMP_API_KEY");

// Create wallet
const wallet = await fetch(`${BASE}/wallet`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY, "x-hyperpump-network": NETWORK },
  body: "{}",
}).then(r => r.json());

// Launch token
const token = await fetch(`${BASE}/create-token`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY, "x-hyperpump-network": NETWORK },
  body: JSON.stringify({
    privateKey: wallet.privateKey,
    name: "AgentCoin",
    symbol: "AGENT",
    creatorFeeBps: 40,
  }),
}).then(r => r.json());

// Quote before buying
const quote = await fetch(
  `${BASE}/quote?token=${token.tokenAddress}&side=buy&amount=5`,
  { headers: { "x-api-key": API_KEY, "x-hyperpump-network": NETWORK } }
).then(r => r.json());
console.log(`Would get ${quote.tokensOut} tokens`);

// Buy
const buy = await fetch(`${BASE}/buy`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY, "x-hyperpump-network": NETWORK },
  body: JSON.stringify({
    privateKey: wallet.privateKey,
    token: token.tokenAddress,
    amountHype: "5",
  }),
}).then(r => r.json());

cURL — Full Flow

# Generate wallet
curl -X POST /api/agent/wallet \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{}'

# Create token
curl -X POST /api/agent/create-token \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{"privateKey":"0xKEY","name":"Test","symbol":"TST","creatorFeeBps":40}'

# Get quote
curl "/api/agent/quote?token=0xTOKEN&side=buy&amount=5" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet"

# Buy
curl -X POST /api/agent/buy \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{"privateKey":"0xKEY","token":"0xTOKEN","amountHype":"5"}'

# Sell
curl -X POST /api/agent/sell \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HYPERPUMP_API_KEY" \
  -H "x-hyperpump-network: mainnet" \
  -d '{"privateKey":"0xKEY","token":"0xTOKEN","amountTokens":"50000000"}'

Error Handling

All errors return {"error":{"code":"SOME_CODE","message":"Human readable message"}} with an HTTP status code.

Network Info