---

name: heytraders description: Use when an authorized external HTTP client with a pre-issued HeyTraders API key must research markets, backtest strategies, inspect owned trading data, or manage orders.

HeyTraders

Overview

Use this compatibility skill only for a client that already has a user-owned HeyTraders API key. Public self-registration and claim-code linking are disabled. OpenClaw clients should use the command-based HeyTraders plugin and its Agent-owned browser session instead of this HTTP API skill.

The HTTP contract is live and discoverable: load the common contract, the relevant domain topic, and OpenAPI before constructing a request. Do not rely on remembered endpoint fields.

Connection

External API keys are not Bearer tokens. Never put a key in a URL, prompt, log, source file, or payment payload.

Successful 2xx responses are the endpoint resource itself; there is no common success or data wrapper. Errors use HTTP 4xx/5xx and:

{"type":"error","error":{"code":"ERROR_CODE","message":"...","suggestion":"...","details":{}}}

Branch on HTTP status, then error.code. Honor Retry-After, rate-limit, and payment headers. Read the common contract for quota, x402, and retry semantics.

Bootstrap

1. Require a pre-issued user-owned key. If none exists, stop and ask the operator to create one in authenticated HeyTraders settings; do not call an undocumented registration or linking endpoint.
2. Fetch GET /v1/docs/common and GET /v1/docs without authentication.
3. For a key with a legacy Agent profile, call GET /v1/meta/agents/me with X-API-Key; its scopes, tier, and quota are current authority. An AGENT_NOT_FOUND response does not authorize creating a profile through a public endpoint.
4. Select a topic from the catalog. Fetch GET /v1/docs/{topic} with Accept: text/markdown.
5. Read the operation in GET /v1/openapi.json. Check its security field, then use its exact method, path, parameters, body union, response schema, and x-heytraders-required-scopes when present.

Minimal discovery example:

BASE_URL="https://api.hey-traders.com/v1"
curl -sS "$BASE_URL/docs"
curl -sS "$BASE_URL/docs/api/market/core" -H "Accept: text/markdown"

OpenAPI authentication metadata

Every operation must contain security. security: [] means no credential is required. security: [{"ApiKeyAuth": []}] means send the current key in X-API-Key. An authenticated operation can omit x-heytraders-required-scopes; when present, that extension lists additional capability scopes required by the operation. If security is missing, refresh Docs and OpenAPI once, then stop and report a server contract inconsistency instead of guessing authentication or scopes.

Ownership and scopes

A user-owned API key receives scopes in authenticated HeyTraders settings. There is no public flow that converts a provisional or unowned key into a user-owned key. Never request a user's browser JWT, Agent session token, or OpenClaw identity key.

agents/me uses ApiKeyAuth but requires no additional capability scope. A trade-mode live request can dynamically require trade in addition to its baseline metadata.

Topic routing

Safety rules

• Discover identifiers; never invent exchange, account, ticker, token, job, or subscription IDs.
• Before an order, verify trade, account ownership, the exchange ticker, and account-specific symbol capabilities. Do not send Idempotency-Key on an order create; HeyTraders creates its internal transport key at request ingress. client_order_id remains venue identity rather than HTTP retry state.
• Ask the human before destructive bulk cancellation, position closing, account deletion, or real-money mode changes.
• Backtest acceptance is asynchronous. Poll status to a terminal state and use the returned result identity.
• After live create, pause, resume, unsubscribe, or mode switch, trust returned effective_* fields and re-read the effective subscription. Requested state is not proof of runtime state.
• 401 means key/authentication failure; 403 means ownership/scope/policy denial; 422 means correct the request; 429 means wait or follow quota guidance. Distinguish 502 upstream failure, 503 unavailable infrastructure, and 504 upstream timeout.
• Do not pay while provisional. For an eligible user-owned key, use only the exact x402 challenge from the response, never reuse a proof, and verify effective tier/quota with agents/me after settlement.

Common mistakes