Agent Registration

Agents are authorized sub-accounts that interact with the HyperQuote API on behalf of an owner wallet. Each agent has its own API key, signing wallet, and set of permitted roles.

What Are Agents?

An agent represents a programmatic trading entity (bot, script, or service) that operates under the authority of a human-controlled owner wallet. The owner signs a one-time registration message to prove wallet ownership, and HyperQuote issues an API key for the agent.

Key properties of agents:

• Separate signing wallet — Agents use a dedicated hot wallet for signing, keeping the owner’s main wallet offline
• Role-based access — Each agent is scoped to specific capabilities (taker, maker, monitor)
• Per-owner limits — A single owner wallet can register up to 10 agents
• Auditable — All agent actions are logged with the agent ID and IP address

Agent Roles

Roles can be combined. For example, ["taker", "monitor"] grants both trading and read access.

Register an Agent

POST /api/v1/agent/register

Register a new trading agent. The owner wallet must sign an EIP-191 message to prove ownership.

Request Body

Signed Message Format

The owner must sign the following message with their ownerWallet:

HyperQuote Agent: {name}:{agentWallet}:{timestamp}

The agentWallet in the message must be lowercased. The timestamp must be within 5 minutes of the server’s current time.

Example Request

import { Wallet } from "ethers";
 
const ownerWallet = new Wallet(process.env.OWNER_PRIVATE_KEY!);
const agentWallet = "0x70997970c51812dc3a010c7d01b50e0d17dc79c8";
const name = "Clawbot Taker";
const timestamp = Math.floor(Date.now() / 1000);
 
const message = `HyperQuote Agent: ${name}:${agentWallet.toLowerCase()}:${timestamp}`;
const signature = await ownerWallet.signMessage(message);
 
const res = await fetch("https://hyperquote.xyz/api/v1/agent/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name,
    ownerWallet: ownerWallet.address,
    agentWallet,
    roles: ["taker", "monitor"],
    description: "Automated RFQ taker bot",
    signature,
    timestamp,
  }),
});
 
const data = await res.json();
console.log("API Key:", data.apiKey); // hq_live_... -- store this securely!

curl -X POST https://hyperquote.xyz/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clawbot Taker",
    "ownerWallet": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    "agentWallet": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
    "roles": ["taker", "monitor"],
    "description": "Automated RFQ taker bot",
    "signature": "0x...",
    "timestamp": 1710000000
  }'

Response (201 Created)

{
  "agentId": "clx1abc2d0001...",
  "apiKey": "hq_live_a1b2c3d4e5f6g7h8i9j0...",
  "prefix": "hq_live_a1b2",
  "name": "Clawbot Taker",
  "roles": ["taker", "monitor"],
  "wallet": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
  "owner": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"
}

Error Responses

Verify Agent

GET /api/v1/agent/auth

Verify your API key and inspect agent configuration.

Headers: Authorization: Bearer hq_live_...

Response (200 OK)

{
  "agentId": "clx1abc2d0001...",
  "name": "Clawbot Taker",
  "roles": ["taker", "monitor"],
  "wallet": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
  "owner": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "rateLimit": {
    "perMinute": 60,
    "perHour": 1000
  }
}

Key Rotation

POST /api/v1/agent/keys/rotate

Rotate an agent’s API key. Authenticated with the current API key. The old key is invalidated immediately.

Headers: Authorization: Bearer hq_live_...

Request Body: None required.

Example

const res = await fetch("https://hyperquote.xyz/api/v1/agent/keys/rotate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${currentApiKey}`,
  },
});
 
const data = await res.json();
console.log("New API Key:", data.apiKey);
// Update your environment with the new key immediately

Response (200 OK)

{
  "agentId": "clx1abc2d0001...",
  "apiKey": "hq_live_x9y8z7w6v5u4...",
  "prefix": "hq_live_x9y8",
  "rotatedAt": "2026-03-10T12:00:00.000Z",
  "message": "API key rotated successfully. The old key is now invalid."
}

Rate Limits for Registration

Registration is rate-limited per IP address to prevent abuse:

Exceeding these limits returns a 429 response with a Retry-After header indicating how many seconds to wait before retrying.