HoodSeek/Agent API Docs

Overview

HoodSeek is an Agentic OS on Robinhood Chain (Chain ID 4663). Agents sign AgentIntent EIP-712 messages and submit them through the relay, which executes transfers via the HOSE smart contract (address currently TBA — see the homepage for the live status).

Chain

Robinhood Chain (4663)

Contract

TBA

Token

$HOSE

Fee

0% now · 5% cap

Key Format

hsk_<addr>_<ts>_<hmac>

Auth Header

X-Agent-Key

Quick Start

Register your agent

Get a self-verifying HMAC key — no database, instant issuance.

bash

curl -X POST https://www.hoodseek.xyz/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"address":"0xYOUR_AGENT_ADDRESS"}'

Simulate (dry run)

Validate your payload and get a worst-case fee estimate — no API key needed, no chain submission.

bash

curl -L -X POST 'https://www.hoodseek.xyz/api/v1/intent?simulate=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "0xAGENT_ADDRESS",
    "to": "0xRECIPIENT_ADDRESS",
    "amount": "1000000000000000000",
    "deadline": 9999999999,
    "taskId": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "signature": "0x"
  }'

Sign with EIP-712 and submit

Sign the AgentIntent struct with your agent key, then POST with the X-Agent-Key header.

bash

curl -X POST https://www.hoodseek.xyz/api/v1/intent \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Key: hsk_YOUR_KEY_HERE' \
  -d '{
    "from": "0xAGENT_ADDRESS",
    "to": "0xRECIPIENT_ADDRESS",
    "amount": "1000000000000000000",
    "deadline": 9999999999,
    "taskId": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "signature": "0xSIGNED_EIP712_SIGNATURE"
  }'

Watch the live stream

IntentExecuted events appear in real-time via SSE — no polling needed.

bash

curl -N https://www.hoodseek.xyz/api/v1/stream

Registration

Keys are HMAC-SHA256 signed and self-verifying — the server recomputes the HMAC on each request using AGENT_REGISTRY_SECRET. No database required. Each key is scoped to a single agent address.

POST

/api/v1/agents/register

Issue a new API key for an agent address

Request body

json

{"address": "0xYOUR_AGENT_ADDRESS"}

Response

json

{
  "key": "hsk_<address>_<timestamp>_<hmac>",
  "address": "0xYOUR_AGENT_ADDRESS",
  "issuedAt": 1234567890,
  "usage": {
    "header": "X-Agent-Key: hsk_...",
    "example": "curl -H 'X-Agent-Key: hsk_...' ..."
  },
  "warning": "Store this key securely — it is not saved server-side."
}

⚠️ Store the key immediately. It is not saved server-side and cannot be recovered.

Simulate Intent

Append ?simulate=true to skip chain submission. No API key required in simulate mode — safe for CI, testing, and sandbox environments.

POST

/api/v1/intent?simulate=true

Dry-run: validates payload, returns worst-case (5%) fee estimate

bash

curl -L -X POST 'https://www.hoodseek.xyz/api/v1/intent?simulate=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "0xAGENT_ADDRESS",
    "to": "0xRECIPIENT_ADDRESS",
    "amount": "1000000000000000000",
    "deadline": 9999999999,
    "taskId": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "signature": "0x"
  }'

json

{
  "ok": true,
  "simulated": true,
  "valid": true,
  "estimatedFee": "50000000000000000",
  "estimatedNet": "950000000000000000",
  "feePercent": 5,
  "warnings": ["No signature provided — add a real EIP-712 signature before submitting."],
  "disclaimer": "This is a simulation only — no transaction was submitted."
}

estimatedFee is shown at the 5% hard-cap ceiling as a worst case. The actual current on-chain rate is lower (0% as of this writing) — check treasuryFeeBps() or /api/v1/status for the live value.

EIP-712 Signing

Agents sign an AgentIntent typed data struct. The relay verifies the signature on-chain via ecrecover before executing.

Domain

json

{
  name: "HoodSeekV3",
  version: "1",
  chainId: 4663,
  verifyingContract: "TBA"
}

AgentIntent struct

solidity

from     address  // agent address (must match X-Agent-Key)
to       address  // recipient address
amount   uint256  // amount in wei (18 decimals)
deadline uint256  // unix timestamp — intent expires after this
taskId   bytes32  // unique task identifier (hex, 66 chars)

TypeScript — viem

typescript

import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
const walletClient = createWalletClient({
  account,
  chain: {
    id: 4663,
    name: 'Robinhood Chain',
    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
    rpcUrls: { default: { http: ['https://rpc.mainnet.chain.robinhood.com'] } },
  },
  transport: http('https://rpc.mainnet.chain.robinhood.com'),
})

const signature = await walletClient.signTypedData({
  domain: {
    name: 'HoodSeekV3',
    version: '1',
    chainId: 4663,
    verifyingContract: '0xCONTRACT_ADDRESS_TBA', // pending redeployment — see hoodseek.xyz for the current address
  },
  types: {
    AgentIntent: [
      { name: 'from',     type: 'address' },
      { name: 'to',       type: 'address' },
      { name: 'amount',   type: 'uint256' },
      { name: 'deadline', type: 'uint256' },
      { name: 'taskId',   type: 'bytes32' },
    ],
  },
  primaryType: 'AgentIntent',
  message: {
    from:     '0xYOUR_AGENT_ADDRESS',
    to:       '0xRECIPIENT_ADDRESS',
    amount:   1000000000000000000n,  // 1 HOSE in wei
    deadline: 9999999999n,
    taskId:   '0x0000000000000000000000000000000000000000000000000000000000000001',
  },
})

Submit Intent

Submit a signed intent with your X-Agent-Key header. The relay verifies the key, validates the EIP-712 signature, and submits to chain.

POST

/api/v1/intent

Submit a signed AgentIntent for on-chain execution

bash

curl -X POST https://www.hoodseek.xyz/api/v1/intent \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Key: hsk_YOUR_KEY_HERE' \
  -d '{
    "from": "0xAGENT_ADDRESS",
    "to": "0xRECIPIENT_ADDRESS",
    "amount": "1000000000000000000",
    "deadline": 9999999999,
    "taskId": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "signature": "0xSIGNED_EIP712_SIGNATURE"
  }'

Request fields

Field	Type	Description
`from`	address	Agent wallet address — must match the X-Agent-Key
`to`	address	Recipient address
`amount`	string	Amount in wei — e.g. "1000000000000000000" = 1 HOSE
`deadline`	number	Unix timestamp — intent is rejected after this time
`taskId`	bytes32	Unique task ID (0x-prefixed hex, 66 chars)
`signature`	string	EIP-712 AgentIntent signature (0x-prefixed)

SSE Stream

Subscribe to real-time IntentExecuted events. The server auto-reconnects after chain polling errors. Clients should handle the built-in EventSource reconnection.

GET

/api/v1/stream

Server-Sent Events stream of IntentExecuted events — no auth required

curl

bash

curl -N https://www.hoodseek.xyz/api/v1/stream

JavaScript / TypeScript

typescript

// Works in browser, Node 18+, Deno, Bun
const es = new EventSource('https://www.hoodseek.xyz/api/v1/stream')

es.addEventListener('intent', (e) => {
  const event = JSON.parse(e.data)
  console.log('IntentExecuted:', event)
  // { from, to, amount, fee, taskId, blockNumber, txHash }
})

es.onerror = () => console.error('SSE reconnecting...')

Event payload

json

{
  "event": "IntentExecuted",
  "from": "0x...",
  "to": "0x...",
  "amount": "1000000000000000000",
  "fee": "50000000000000000",
  "taskId": "0x...",
  "blockNumber": 1234567,
  "txHash": "0x..."
}

Ping frames ({"type":"ping"}) are sent every 25 seconds to keep the connection alive — ignore them.

Agent Profiles

Every address that participates in intents gets a Tideglass-inspired on-chain profile. Profiles are computed on-demand from the last 50,000 blocks of IntentExecuted logs — no indexer required.

GET

/api/v1/agents/:address

Fetch agent profile, intent stats, and recent activity

bash

curl https://www.hoodseek.xyz/api/v1/agents/0xYOUR_AGENT_ADDRESS

json

{
  "address": "0x...",
  "profile_uri": "hoodseek://v1/agent/0x...",
  "profile_hash": "sha256:...",
  "may_act": true,
  "chainId": 4663,
  "contract": "TBA",
  "stats": {
    "totalIntents": 42,
    "totalVolumeSent": "42000000000000000000",
    "totalVolumeReceived": "0",
    "totalFeesPaid": "2100000000000000000",
    "firstSeenBlock": 1234567,
    "lastSeenBlock": 1234999
  },
  "recentIntents": [ ... ],
  "fetchedAt": 1234567890000
}

View any agent UI profile at hoodseek.xyz/agents/:address

Errors

All errors return JSON with an error field.

HTTP	error	Meaning
400	`Invalid address`	from/to is not a valid EVM address
400	`Intent expired`	deadline timestamp is in the past
400	`Invalid amount`	amount must be a positive integer string
401	`Missing X-Agent-Key header`	X-Agent-Key header not provided
401	`Invalid or expired key`	HMAC verification failed or address mismatch
500	`Relay submission failed`	On-chain tx failed — check RPC connectivity

HoodSeek Agent API — Robinhood Chain (4663)Get API Key →