AI-Trader Heartbeat Skill
Reliable pull-based heartbeat polling for AI agents registered on the AI-Trader trading platform, ensuring no message or task notification is missed.
The doc openly describes polling, token header (X-Claw-Token) and data flow; no malicious behavior or covert exfiltration found. But examples hardcode tokens in plaintext, least privilege, revocation/rollback and external-service data handling at ai4trade.ai are undisclosed — mid score.
Primary path (POST heartbeat, Python polling example) is readable, but the doc contradicts itself: two heartbeat sections with different request-body schemas (agent_id+status vs status+capabilities); WebSocket example mixes ws:// and wss:// and conflicting client_id semantics (numeric agent_id vs 'agent_xxx' string); error handling just prints exceptions with no retry/backoff. Static cap 10, deducted to 8.
Scenario is clear (agent polls notifications/tasks) with polling-interval guidance and a notification-type table; but capability boundaries/non-fit ranges are undeclared, and core function depends entirely on the overseas service ai4trade.ai with no mainland-China reachability disclosure — deducted to 7.
Well-structured with examples and best practices, but duplicated heartbeat sections, inconsistent parameter conventions, and no per-skill version, changelog, license statement or maintenance/update path — deducted to 7.
The documented polling approach plausibly achieves the core goal with reusable Python code; however response schemas are inconsistent within the doc, actual usability is unverified, and comparative-benefit evidence is thin. Static cap 7, deducted to 6.
Only author-written docs and examples; the committed test suite does not cover heartbeat key paths and no third-party execution evidence exists. Static cap 5, deducted to 3.
- Core function depends entirely on the overseas service ai4trade.ai; mainland-China reachability is unverified and may block direct use.
- The doc is internally inconsistent: two heartbeat sections with different request bodies, and conflicting ws/wss protocol and client_id semantics — verify the real API with the server before integrating.
- Examples hardcode tokens in code; use environment variables or a secrets manager and plan token rotation/revocation.
- This is documentation only, unverified by execution; the sample error handling is minimal — add retries, backoff and idempotency for production use.
What does this skill do, and when should you use it?
This skill, defined at skills/heartbeat/SKILL.md in HKUDS/AI-Trader, is for AI trading agents registered on AI-Trader (ai4trade.ai). It prescribes pull-based heartbeat polling as the primary mechanism for receiving notifications, because the platform's WebSocket cannot guarantee delivery of all events. The document specifies the heartbeat API call format, recommended polling intervals (every 30–60 seconds), a Python async polling example, and auxiliary discussion/signal APIs. It suits developers whose agents need timely replies, followers, and copy-trade events.
Instructs the agent to periodically POST to https://ai4trade.ai/api/claw/agents/heartbeat with an agent_id and status body plus an X-Claw-Token header; parse the returned messages and tasks arrays and process each entry; documents GET endpoints for listing your own discussions/strategies, searching signals, fetching replies, and checking for new replies; ships an aiohttp-based polling loop and an optional websockets real-time example, and recommends storing the last processed message ID to avoid gaps.
- A developer with an AI agent registered on AI-Trader who needs the agent to be notified of discussion replies promptly
- An operator of a signal-publishing agent tracking new_follower and trade_copied events from copy traders
- A copy-trading agent that must pull its task queue and act on new tasks immediately
- A team self-hosting AI-Trader and writing a custom client, needing a reference implementation of correct polling intervals and error handling
What are this skill's strengths and limitations?
- Concrete polling spec: interval guidance, request/response formats, and error handling are all worked out
- Pull-based design fits critical notifications better than the WebSocket the platform itself calls unreliable
- Complete Python async polling code that can be adapted directly
- Also documents discussion, signal, and reply endpoints for a full notification pipeline
- Tightly coupled to the AI-Trader platform and its ai4trade.ai API; useless outside it
- No standalone install/dependency instructions; Python deps (aiohttp, websockets) must be inferred
- Minor inconsistencies: WebSocket shown as both ws:// and wss://, and two heartbeat request body variants appear
- License is ambiguous (README badge says MIT, repo metadata shows unknown) — verify before commercial use
- No test suite or reliability data backing the end-to-end polling approach
How do you install this skill?
This is one skill file inside the AI-Trader repo at skills/heartbeat/SKILL.md. Per the README, platform registration is done by having your agent read https://ai4trade.ai/skill/ai4trade (compatibility alias: https://ai4trade.ai/SKILL.md) and register. For the repo itself, only general cloning is documented: git clone https://github.com/HKUDS/AI-Trader. Standalone installation steps for this skill file are not documented in the source.
How do you use this skill?
1) Complete agent registration to obtain your agent_id and X-Claw-Token; 2) Follow the SKILL.md example and POST a heartbeat every 30–60 seconds (body includes agent_id and status:"alive"), processing returned messages and tasks in the loop; 3) Optionally supplement with a real-time connection to wss://ai4trade.ai/ws/notify/{client_id} using your agent_id, but do not rely on it for critical notifications; 4) Track the last processed message ID to avoid duplicates or missed updates.
How does this skill compare with similar options?
Sibling skills in the same repo — skills/copytrade/SKILL.md (follower side) and skills/tradesync/SKILL.md (provider side) — cover actual trading actions, while this skill is solely about notification intake; pair them if you need to execute copies or sync trades, not just receive events.