# n8n

Two ways to use Onekey in [n8n](https://n8n.io): 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](https://onekey.dev/docs/authentication.md).
- 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

1. 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.)
2. 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.

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

3. 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](https://onekey.dev/docs/response-envelope.md).

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.

1. **Schedule Trigger**: every day at 08:00.
2. **Edit Fields (Set)**: one item per repository, with `owner` and `repo`.
3. **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.
4. **IF**: `{{ $json.success }}` is true. The false branch is where a failed item goes; see troubleshooting.
5. 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`](https://onekey.dev/docs/api/github/latest_release.md), **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](https://onekey.dev/docs/caching.md) is free, and a call that fails is refunded. Add [`github.repo`](https://onekey.dev/docs/api/github/repo.md) (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](https://onekey.dev/docs/monitors.md) does the checking for you and calls your workflow only when the data changed:

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

```bash
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"}
  }'
```

3. Save the `webhook.secret` from the answer; it is shown once.
4. 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](https://onekey.dev/docs/monitors.md#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.

1. Add an **AI Agent** node with a chat model of your choice.
2. 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](https://onekey.dev/docs/mcp.md#the-eleven-tools) page
3. 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](https://onekey.dev/docs/mcp.md#the-eleven-tools) first, and use a key with a credit limit.

## Troubleshooting

| Symptom | Likely error | What to do |
| --- | --- | --- |
| Every call is refused | [`UNAUTHORIZED`](https://onekey.dev/docs/errors.md#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`](https://onekey.dev/docs/errors.md#insufficient-credits) or [`KEY_BUDGET_EXCEEDED`](https://onekey.dev/docs/errors.md#key-budget-exceeded) | Nothing was charged for the refused call. Top up, or raise the key's [credit limit](https://onekey.dev/docs/key-limits.md). Do not retry in a loop. |
| "Too many requests" | [`RATE_LIMITED`](https://onekey.dev/docs/errors.md#rate-limited) | Wait the `Retry-After` seconds. Loops that call once per item should add a pause. See [Rate limits](https://onekey.dev/docs/rate-limits.md). |
| A parameter is rejected | [`INVALID_PARAMS`](https://onekey.dev/docs/errors.md#invalid-params) | Read the parameter names from the endpoint's page (or `describe_endpoint`); do not guess them. |
| A platform fails intermittently | [`UPSTREAM_ERROR`](https://onekey.dev/docs/errors.md#upstream-error) / [`UPSTREAM_TIMEOUT`](https://onekey.dev/docs/errors.md#upstream-timeout) | The source platform, not you. Refunded; retry with backoff and check [status](https://onekey.dev/docs/status.md). |
| 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`](https://onekey.dev/docs/errors.md#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`](https://onekey.dev/docs/errors.md#webhook-disabled)); `PATCH` the URL to re-enable it. See [Monitors](https://onekey.dev/docs/monitors.md#delivery-retries-and-auto-disable). |

## Untested

- The **HTTP Request** node settings follow n8n's current [documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) (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](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/) 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](https://onekey.dev/docs/monitors.md), [MCP server](https://onekey.dev/docs/mcp.md), [Errors](https://onekey.dev/docs/errors.md).