n8n

Two ways to use Onekey in n8n: call the REST API from an HTTP Request node (best for scheduled and webhook workflows), or connect the hosted MCP server to an AI Agent with the MCP Client Tool node.

Prerequisites#

An n8n instance (cloud or self-hosted) and a Onekey API key.
For the webhook path below, an n8n instance reachable from the internet over HTTPS. Onekey refuses webhook URLs on private or local addresses.

The 5-minute path: one HTTP Request node#

Create a credential: Header Auth, name x-api-key, value your key. (n8n lists "Header auth" among its generic credential types for the HTTP Request node.)
Add an HTTP Request node. Either fill it in by hand (method GET, the URL below, authentication Generic Credential Type, then your Header Auth credential), or use Import cURL and paste the command, then attach the credential.

shell

curl "https://api.onekey.dev/v1/github/repo?owner=facebook&repo=react" \
  -H "x-api-key: YOUR_API_KEY"

Run the node. Your data is under data, the price of the call is metadata.credits_charged (1 for this endpoint), and success is false with an error object if it failed. See the response format.

The star count is at data.entity.stats.stars and the name at data.entity.name. In an n8n expression that is {{ $json.data.entity.stats.stars }}.

Example: a daily release watch#

A workflow that checks the latest release of the projects you depend on each morning.

Schedule Trigger: every day at 08:00.
Edit Fields (Set): one item per repository, with owner and repo.
HTTP Request: GET https://api.onekey.dev/v1/github/latest_release with Send Query Parameters on: owner = {{ $json.owner }}, repo = {{ $json.repo }}. Use the Header Auth credential from above. The node runs once per incoming item.
IF: {{ $json.success }} is true. The false branch is where a failed item goes; see troubleshooting.
A notification node (Slack, email, anything) using {{ $json.data.content.title }} (the release name) and {{ $json.data.content.url }} (its link).

Endpoint: github.latest_release, 1 credit, parameters owner and repo.

Cost#

One credit per repository per run. Ten repositories checked daily is 10 credits a day, at most 300 a month. A repeat call inside the endpoint's cache window is free, and a call that fails is refunded. Add github.repo (also 1 credit) if you want star counts in the same message, and the cost doubles.

Better than polling: a monitor that calls n8n#

Checking every day whether something changed costs a call whether or not it did. A monitor does the checking for you and calls your workflow only when the data changed:

Add a Webhook node (method POST) and copy its Production URL.
Create the monitor, with that URL as the webhook:

shell

curl -X POST "https://api.onekey.dev/v1/monitors" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "react releases",
    "target": {"platform": "github", "endpoint": "latest_release", "params": {"owner": "facebook", "repo": "react"}},
    "interval": "24h",
    "rules": [{"on": "any_change"}],
    "webhook": {"url": "YOUR_N8N_WEBHOOK_PRODUCTION_URL"}
  }'

Save the webhook.secret from the answer; it is shown once.
Call POST /v1/monitors/{id}/webhook/test to send a signed test event to the workflow, then activate the workflow.

This monitor costs 1 credit per run, so 30 credits a month at a 24-hour interval, and it fires only when the release changes. The event carries the new release under body.data and what changed under body.delta. Every delivery is signed; see Verify the signature. Verifying needs the raw request body, so check whether your n8n version's Webhook node can pass it on. If it cannot, make the webhook path long and random so the URL itself is hard to guess, and do not rely on it alone for anything sensitive.

Let an AI agent use it: MCP Client Tool#

n8n's MCP Client Tool node connects an AI Agent node to an MCP server.

Add an AI Agent node with a chat model of your choice.
Add an MCP Client Tool node to the agent's tools and set:
Endpoint: https://api.onekey.dev/mcp
Server Transport: HTTP Streamable (n8n documents its older SSE transport as deprecated)
Authentication: Bearer, with your Onekey key as the token (the node also supports a generic header, so x-api-key works too)
Tools to include: all, or pick from the eleven listed on the MCP server page
Ask it something concrete: "Find the Onekey endpoint for the latest release of a GitHub repo, tell me its price, then check facebook/react."

The agent will normally call the free discovery tools (search_endpoints, describe_endpoint) and then call_endpoint, which spends the endpoint's price. Read what the tools cost first, and use a key with a credit limit.

Troubleshooting#

Symptom	Likely error	What to do
Every call is refused	`UNAUTHORIZED`	The key is missing, misspelled or revoked. Check the header name and that the value has no stray spaces or quotes.
Calls stop working partway through a job	`INSUFFICIENT_CREDITS` or `KEY_BUDGET_EXCEEDED`	Nothing was charged for the refused call. Top up, or raise the key's credit limit. Do not retry in a loop.
"Too many requests"	`RATE_LIMITED`	Wait the `Retry-After` seconds. Loops that call once per item should add a pause. See Rate limits.
A parameter is rejected	`INVALID_PARAMS`	Read the parameter names from the endpoint's page (or `describe_endpoint`); do not guess them.
A platform fails intermittently	`UPSTREAM_ERROR` / `UPSTREAM_TIMEOUT`	The source platform, not you. Refunded; retry with backoff and check status.
The HTTP Request node shows an error but the body says `success: false`	any	Onekey answers a failure with a non-2xx status and an `error` object. Turn on the node's option to include the status and body (or "never error") if you want to branch on `error.type` yourself.
The monitor is created but your workflow never fires	`WEBHOOK_URL_REJECTED` at creation, or a paused webhook	The URL must be `https` on port 443 to a public host. If deliveries fail 10 times in a row the webhook is switched off (`WEBHOOK_DISABLED`); `PATCH` the URL to re-enable it. See Monitors.

Untested#

The HTTP Request node settings follow n8n's current documentation (generic Header Auth, query parameters, Import cURL). The endpoint and its fields were checked against Onekey's own registry and recorded responses. The workflow itself was not run in n8n.
The MCP Client Tool settings follow n8n's documentation as of 2026-09-30. Field labels can differ between n8n versions. The hosted MCP server was tested with the official MCP client, not with n8n.
Whether the Webhook node exposes the raw body for signature checks was not verified.

Next#

Monitors, MCP server, Errors.