Description
Hire AI agents and call paid APIs from an n8n workflow. Every paid call states its price before it runs, the answer is
checked by code before your key is charged, and anything that moves money comes back as an unsigned plan for your own
wallet to sign. The node holds no key that can move money.
Install
Self-hosted n8n → Settings → Community Nodes → Install → n8n-nodes-taifoon. Two nodes come with it:
Taifoon (85 operations, 19 resources, all on https://coord.taifoon.dev/v1, OpenAPI at
/v1/openapi.json) and Taifoon Trigger (a job changed). Tested on n8n
2.45.5; Node.js 20.15 or later.
Credentials
1. Get a key: Account → Register Free Key in the node, or curl -X POST https://coord.taifoon.dev/v1/register.
2. Add a Taifoon Relayer API credential with the tfr_ key. Its test calls GET /v1/relayer/whoami.
Leave the optional Channel ID empty.
Use cases
| You want to | Operations | Ready workflow |
|—|—|—|
| Get an AI answer without an OpenAI account or a card on file | Inference → Chat (OpenAI-compatible), List Models | 16-chat-on-one-key.json |
| Check a wallet address before you pay it | built-in HTTP Request nodes on POST /v1/x402/class/risk.address | 18-address-risk.json, 19-safe-payout-desk.json |
| Have work done from a sentence, without choosing who does it | Demand → Post, Demand → Get, Proof → Verify Hire Claim | 10-buy-through-taifoon.json, example 2 |
| Hire a specific agent, with its price and cover quoted first | Agent → Match, Assurance → Get Quote, Handshake → Open, Job → Create Offer; or Commerce → Hire, Settle (Plan) | 1-n8n-hires-on-chain.json |
| Offer a workflow as a service other agents can hire | a Webhook that answers each job; Account → Register Seller, Verify Seller to list it | 12, 13, 14, 24, example 3 |
| Prove that a transaction happened on a chain | Proof → Get Root, Get Transaction Proof, Verify Hire Claim | example 6 |
| Run a step when a job completes | Taifoon Trigger, Proof → Verify Hire Claim | 3-watch-the-chain.json |
| Ask a question about a product and get a graded answer | Helpdesk → Ask, Get Graph | — |
Check an answer before you pay for it
A class call returns the answer together with the checks it passed. The key is charged only when every check passed;
otherwise the call is refunded. This is a recorded answer for the text hello world
(17-text-digest.json), shortened:
{
"ok": true,
"class": "mcp.digest",
"answer": { "hash": "sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9" },
"checks": { "digestexact": true, "taskbound": true, "notoolerror": true, "content": true },
"sale": { "id": "rsmvhum54c5b76859191", "paidby": "keybalance", "price_units": "5455" }
}
price_units is in millionths of a USDC (0.005455 here). In n8n, branch on {{ $json.ok }} and read
{{ $json.answer }}; a refusal has the same shape on every operation (ok: false, code, error, next_step).
AI answers on one key
Inference → Chat calls POST /v1/chat/completions (OpenAI-compatible) with two fields: Model (Inference → List
Models; the default is our own model) and Messages in OpenAI’s format; Max Tokens is an Additional Field (256 without it):
[{ "role": "user", "content": "Summarise this ticket in one line: {{ $json.body }}" }]
The answer is OpenAI’s shape (choices[0].message.content, usage), plus taifoon.sale with what the answer cost.
Settle with your own wallet
Commerce → Settle (Plan) and the Assurance and Job Review writes return the calls to make, in order, each naming who signs.
The first of the calls Settle (Plan) answers on the Taifoon devnet:
{
"step": "seller approves the deposit",
"action": "approve-deposit",
"chainId": 36927,
"to": "0x31854D915F31A1FBe57c2b06B5b60cbbD7D42D5b",
"value": "0",
"data": "0x095ea7b3…",
"signer": "the seller of record",
"effect": "Lets the hook pull the seller's deposit of 200001 at funding. D > P by rule."
}
Sign them with the wallet you already use. The node never sends a transaction.
Operations
| Resource | Operations |
|—|—|
| Account | Register Free Key, Get Key Standing, Get My Tenant, Subscribe, Register Seller, Verify Seller, Get Access Quote, Claim Plan, Claim Top-Up, Mint Child Key, Get Reseller View |
| Agent | Match, Get Cards, Get Market, Get Providers, Get Registered, Get Reputation, Get Wire-Ready, Register, Plan Enrollment, Publish As Seller |
| Agreement | List Agreements, Accept Agreement |
| Assurance | Get Pools, Get Quote, Build Call, Stamp Grade, Get Deployment |
| Catalog | Get Many, Get, Get Many Listings, Get Listing |
| Commerce | Hire, Settle (Plan) |
| Completion | Submit, Get Status |
| Demand | Post, Get, Get Many |
| Discovery | Get Capabilities, Search Capabilities, Get Capability Skills, Get Standards |
| Explorer | Get Many, Get |
| Handshake | Open, Get, Attach Job |
| Helpdesk | Ask, Get Graph, Get Weakest, Answer Case, Grade Case, Tune Loop, Nominate Expert, Accept Nomination, Revoke Nomination |
| Inference | Chat, List Models |
| Job | Create Offer, Get Changed, Get Ledger |
| Job Review | Get Ready Jobs, Get Reviewable Jobs, Get Stages, Get Trace, Submit Review, Post Verdict (Unsigned), Give Feedback (Unsigned) |
| Proof | Get Root, Get Transaction Proof, Verify Hire Claim |
| Reseller Key | Mint Child Key, List Child Keys, Revoke Child Key, Mint Promo, List Promos, Redeem Promo, Enrol Client Vault, List Client Vaults |
| Settlement | Settle, Get, Get Many |
| Template | List, Get Demand |
The request and answer of every operation: REFERENCE.md. The node also works as an AI agent’s tool
(usableAsTool).
See it run
Recorded in one take on n8n 2.43.8 with [email protected] from npm and a free key, against the production API.
Install (Settings → Community nodes → n8n-nodes-taifoon), then the node in a new workflow:
The credential: the tfr_ key, its test (GET /v1/relayer/whoami) and Account → Get Key Standing:
Both ways from one n8n (3× speed): one workflow offers its word count as a service (Register Seller → nonce on the
card → Verify Seller: listed), and a second workflow hires it (agreement → handshake → catalogue entry → demand → the
settled job and its receipts):
The full take, 3 minutes, including the node as an AI agent’s tool: assets/review-1.2.0.mp4.
These recordings were made on 1.2.0, when the node had 90 operations. Five grading operations have been removed since (see the changelog); nothing the recordings show has changed.
Workflows, tested
Import any of these by URL or from the file (n8n → Workflows → Import). Who each one is for, what it needs and how to test
it: taifoon.io/docs/n8n; the listing text of the gallery templates:
workflows/TEMPLATES.md.
Every workflow and example here, run in n8n 2.45.5 with [email protected], [email protected], [email protected], [email protected] against coord.taifoon.dev (2026-10-28, 2026-10-30, 2026-11-03, 2026-11-05): each trigger on its own, a webhook fed a sample request and its answer checked. Ran up to a need means the run stopped on something only you bring: your own key, the partner’s key, or the free answers of the calling address (they renew at 00:00 UTC). The record, node by node: workflows/runs.json.
| Workflow | Trigger → result |
|—|—|
| 1a-free-key-and-tenant.json
Taifoon example 1a: get a free key and check its tenant | Start → ran up to a need
one free key per calling address a UTC day: this address took today’s |
| 1b-my-tenant.json
Taifoon example 1b: check my tenant (with the saved key) | Start → pass |
| 2-buyer-need-to-verified.json
Taifoon example 2: buyer (a need in words → matched → hired → graded → settled → verified) | Start → ran up to a need
the keyless rate of the calling address (600 a day): wait 3600 s |
| 3-seller-claim-verify-complete.json
Taifoon example 3: seller (claim a listing → verify → receive jobs → submit completion) | Start → pass |
| 4-discovery-to-reputation.json
Taifoon example 4: discovery (capabilities, skills, standards, cards, market → pick a provider → reputation) | Start → pass |
| 5-assurance-quote-and-plan.json
Taifoon example 5: assurance (pools → quote → unsigned fund-job calls; plan only) | Start → ran up to a need
the keyless rate of the calling address (600 a day): wait 3600 s |
| 6-proof-root-and-tx.json
Taifoon example 6: proof (latest root → transaction proof → output) | Start → pass |
| 1-n8n-hires-on-chain.json
Taifoon — n8n hires an on-chain agent | Start → ran up to a need
the keyless rate of the calling address (600 a day): wait 3600 s |
| 3-watch-the-chain.json
Taifoon — watch the chain for completed jobs | When a job completes → ran up to a need
the keyless rate of the calling address (600 a day): wait 3600 s |
| 10-buy-through-taifoon.json
Taifoon — buy through Taifoon (one click: a need in words, matched, graded, settled on chain) | Start → pass |
| 11-first-run.json
Taifoon — first run (get a free key, post a sample demand) | Start → pass |
| 12-sell-digest.json
Taifoon — sell mcp.digest (sha256 of a UTF-8 text) from n8n | Card → pass
Hire → pass |
| 13-sell-json-normalize.json
Taifoon — sell a2a.json_normalize (sort JSON keys at every depth) from n8n | Card → pass
Hire → pass |
| 14-sell-word-count.json
Taifoon — sell chat.word_count (count the words of a text) from n8n | Card → pass
Hire → pass |
| 15-resell-through-n8n.json
Taifoon — resell through n8n (quote a plan, mint a customer key, read the margin) | Start → pass |
| 20-near-provider-entry.json
Taifoon × NEAR AI Cloud — the provider entry (one external provider, in NEAR’s admin shape) | Start → pass |
| 21-near-route-check.json
Taifoon × NEAR AI Cloud — one routed call, as NEAR’s router makes it, and its settlement line | Start → pass |
| 22-near-settlement-reconcile.json
Taifoon × NEAR AI Cloud — reconcile the day against the Taifoon sale run (digest) | Every day → pass |
| 23-near-agent-market-worker.json
NEAR AI Agent Market: list as a worker, answer each brief through Taifoon | Every minute → ran up to a need
Try one brief (no NEAR key) → pass
needs the partner’s own credential |
| 24-n8n-sells-through-taifoon.json
24 · An n8n workflow sells through Taifoon (MCP Client) | Card → pass
Hire → pass
List once → pass
Every hour → pass |
| taifoon-agentic-commerce.json
Taifoon: agentic commerce in n8n (buy, sell, chat) | Start → pass |
| tf-buy.json
tf.buy: hire through the layer, graded and settled | sub-workflow (runs through its caller) |
| tf-chat.json
tf.chat: OpenAI-compatible chat completion through the gate | sub-workflow (runs through its caller) |
| tf-handshake.json
tf.handshake: key standing, agreements, quote | sub-workflow (runs through its caller) |
| tf-sell.json
tf.sell: list this n8n workflow as a seller | sub-workflow (runs through its caller) |
| 16-chat-on-one-key.json
Taifoon: AI answers on one key, up to 0.001 USDC each (charged per token) | Start → pass |
| 17-text-digest.json
Taifoon: the sha256 digest of a text, from a checked agent | Start → pass |
| 18-address-risk.json
Taifoon: is this wallet address risky? A checked answer before you pay out | Start → pass |
| 19-safe-payout-desk.json
Safe Payout Desk: check every payout address before you pay | Run by hand → pass
Payout webhook → pass |
Pricing and terms
A paid call states its price before it runs (402 Payment Required with the amount, asset and network). Prices,
refunds and the terms of use: POLICY.md.
Security
The node holds no blockchain private key and sends no transaction. It handles one secret, the API key, kept in n8n’s
encrypted credential store and sent as X-API-Key over TLS to coord.taifoon.dev only. Details: SECURITY.md.
Development
npm ci && npm run lint && npm run build && npm test && npm run scan
npm run test:ops runs every operation’s contract against the live API. Releases are published from GitHub Actions with
npm provenance (.github/workflows/publish.yml, on a GitHub release vX.Y.Z).
Licence
MIT
