원클릭으로
원클릭으로
| name | okx-affiliate-mcp |
| description | Install and maintain the OKX Affiliate MCP (OAuth) on Hermes Agent. |
| version | 1.0.0 |
| author | Community |
| license | MIT |
| metadata | {"hermes":{"tags":["MCP","OAuth","OKX","Affiliate","Integrations"],"related_skills":["native-mcp"]}} |
Install, authorize, and keep alive the OKX Growth Affiliate MCP
(https://www.okx.com/api/v1/mcp/growth-affiliate-mcp) on Hermes Agent.
After install, Hermes exposes 6 tools (named mcp_okx_affiliate_*):
okx-affiliate-performance-summaryokx-affiliate-invitee-listokx-affiliate-invitee-detailokx-affiliate-link-listokx-affiliate-sub-affiliate-listokx-affiliate-co-inviter-listSee reference/tools-overview.md for what each one returns.
Load this skill when the user asks to:
401 Unauthorized from mcp_okx_affiliate_* tools"The OKX MCP is a remote HTTP MCP with two OAuth quirks that no MCP client currently handles out of the box:
resource parameter (RFC 8707) on every authorize and token
request — omitting it returns invalid_grant: resource does not match./api/v5/mcp/auth/register — not advertised by .well-known.Hermes Agent's native-mcp client supports static HTTP headers but does not
run an OAuth flow. This skill runs the flow with four small stdlib-only
Python scripts (adapted from the upstream
okx/growth-affiliate-tool
repo) and writes the resulting bearer token straight into
~/.hermes/config.yaml. Hermes hot-reloads mcp_servers on config change,
so the MCP appears within seconds — no restart needed.
All credentials live under ~/.hermes/data/okx-affiliate-mcp/ (gitignored):
| File | Content | Written by |
|---|---|---|
client.json | DCR-registered client (client_id, redirect_uris, …) | register.py |
pkce.json | code_verifier, code_challenge, state for this auth | auth.py |
auth_url.txt | URL the user must open in a browser | auth.py |
token.json | access_token, refresh_token, expires_in, obtained_at | exchange.py / refresh.py |
The bearer token in token.json is also mirrored into ~/.hermes/config.yaml
inside a managed block delimited by:
# >>> okx-affiliate-mcp managed block — do not edit by hand >>>
... mcp_servers entry ...
# <<< okx-affiliate-mcp managed block <<<
write_config.py only touches text between those two markers; everything
else in config.yaml is preserved byte-for-byte.
When invoked, always start by running:
python3 SKILL_DIR/scripts/status.py
Branch on the printed state:
state: ok → already installed and token valid; you are done
state: expiring_soon | expired → run scripts/auto_refresh.py (one shot)
state: not_installed → Fresh install (steps 1–4)
state: registered_but_unauthed → resume from Step 2 (auth.py)
state: token_malformed → resume from Step 2 (auth.py)
Replace
SKILL_DIRwith the absolute path to this skill's directory (the directory containingSKILL.md).
python3 SKILL_DIR/scripts/register.py
Writes client.json. Idempotent — safe to re-run.
python3 SKILL_DIR/scripts/auth.py
Prints the URL and saves it to auth_url.txt. Send the URL to the user.
⚠ Before the user clicks Authorize, tell them — explicitly, in plain language — what to expect:
After clicking Authorize, your browser will try to load
http://localhost:8787/callback...and you'll see a blank / "site can't be reached" page. That blank page is the success state. Do not reload or close the tab. Just copy the entire URL from the browser's address bar (it containscode=...&state=...) and paste it back.
On the consent page they should only enable Live Trading → Read-only.
Everything else off. See reference/blank-callback-page.md for the full
walkthrough.
python3 SKILL_DIR/scripts/exchange.py "<callback-url-or-code>"
Accepts either the bare code value or the full callback URL. Verifies
state against pkce.json, exchanges the code, writes token.json.
python3 SKILL_DIR/scripts/write_config.py
Adds (or replaces) the managed mcp_servers.okx_affiliate block in
~/.hermes/config.yaml. Hermes will hot-reload within ~3 seconds.
mcp_servers: keyYAML disallows two top-level mcp_servers: keys. write_config.py will
bail with a clear error. Either:
Ask Hermes to call the MCP:
Show me my affiliate performance summary.
Hermes should call mcp_okx_affiliate_okx_affiliate_performance_summary
and return a numeric payload. If you see 401 Unauthorized, run
scripts/auto_refresh.py and retry.
python3 SKILL_DIR/scripts/auto_refresh.py
This is refresh.py + write_config.py in one shot:
grant_type=refresh_token to OKX (with the mandatory resource
parameter).token.json with the new access_token + refresh_token +
obtained_at.~/.hermes/config.yaml.If refresh.py fails (refresh_token is dead), fall back to a fresh login
— auth.py → exchange.py → write_config.py. client.json is still
valid, so you can skip register.py.
access_token lives ~1 hour. To keep it valid without LLM involvement,
register a cron job that runs auto_refresh.py every 50 minutes. Two
options:
Use the cronjob tool inside Hermes:
schedule: "*/50 * * * *"
prompt: "Run: python3 ~/.hermes/skills/<category>/okx-affiliate-mcp/scripts/auto_refresh.py"
(Replace <category> with wherever the skill is installed. If you cloned
this repo into ~/.hermes/skills/okx-affiliate-mcp/, no category prefix
needed.)
*/50 * * * * /usr/bin/python3 /home/USER/.hermes/skills/okx-affiliate-mcp/scripts/auto_refresh.py >/dev/null 2>&1
Either option keeps config.yaml's bearer token always fresh; the agent
never sees a 401.
If you skip cron, the LLM can recover from a 401 the OpenClaw way: when
any mcp_okx_affiliate_* tool returns 401 / "token expired", load this
skill and run scripts/auto_refresh.py, then retry the original call.
Hermes hot-reloads MCP within a few seconds; if the retry still 401s,
sleep ~3 seconds and try once more.
resource parameter — required on both the authorize request
and the token request, and the refresh request. invalid_grant: resource does not match always means this is missing./api/v5/mcp/auth/register, not the discovery default./api/v5/mcp/auth/token.flow=code query param — without it OKX
may serve a different UI.Python-urllib/3.x gets a
403 error code: 1010. Scripts already send a browser-ish UA.live:read unless the user has a real need; broader
scopes alarm the user on the consent screen and are not used by this MCP.mcp_servers:
block outside our managed region, write_config.py will refuse to write
(see Step 4 above).See reference/oauth-endpoints.md and reference/known-issues.md for full
specs and historical bugs.
rm -rf ~/.hermes/data/okx-affiliate-mcp
# Then delete the managed block between BLOCK_BEGIN/BLOCK_END markers in
# ~/.hermes/config.yaml. Hermes will hot-reload and drop the MCP.
To also revoke OAuth access, sign in to OKX → Connected apps and remove the entry there.
OAuth scripts adapted from
okx/growth-affiliate-tool
(MIT). Hermes-specific glue (status, write_config, auto_refresh) added for
this skill.
Use this skill when the user wants to analyze acquisition or performance trends over multiple months — new invitees per month, conversion rate trajectory, monthly commission, daily-active-trader trends. Triggers: "拉新趋势", "近 N 个月的拉新", "monthly trend", "show me the last 6 months", "DAT history", "when was my peak", "analyze acquisition over time", "what's the YoY". Do NOT use for single-day briefings (use `daily-briefing`) or single-user history (use `whale-deep-dive`).
Use this skill when the user wants to find churning or sleeping users — whales who stopped trading, depositors whose activity dropped, or recently active users showing decline. Triggers: "find churning users", "who's slipping away", "流失预警", "鲸鱼跑了", "sleeping whales", "show me users with declining volume", "last seen", "when did user X stop trading". Do NOT use this for net-new acquisition analysis (use `acquisition-trends`) or for users who are still healthy (use `whale-deep-dive`).
Use this skill when the user wants yesterday's (or today-so-far) affiliate node performance — commission, deposits, new invitees, top traders, top depositors, and action items for the day. Triggers: "yesterday's data", "morning report", "daily briefing", "节点日报", "看下昨日表现", "今天节奏怎么样", "EOD report", "where am I at today". Do NOT use for multi-week or quarterly trends (use `acquisition-trends` instead). Do NOT use for a single user deep dive (use `whale-deep-dive`).
Use this skill when the user wants a curated list of invitees worth nurturing — fresh deposits without trading, mid-tier traders showing momentum, KYC-verified users who haven't deposited, recently activated whales. Triggers: "find high potential users", "who should I reach out to", "潜力用户", "give me a list of users to nurture", "rescue list", "high LTV candidates". Also use when the user asks for a multi-tier prioritization (P0/P1/P2). Do NOT use for a single user deep dive (use `whale-deep-dive`) or for a generic daily briefing (use `daily-briefing`).
Use this skill when the user wants everything known about a single invitee — lifetime totals, recent activity, KYC details, deposit/withdrawal history, and what to do next. Triggers: "pull up UID X", "give me everything on user Y", "deep dive on Z", "prep me to DM user A", "what's user B's history", "show me X's last 30 days". The user usually provides a UID inline. Do NOT use for multi-user lists (use `high-potential-invitees` or `churn-rescue` instead).