n8n-nodes-taliware

TALIWARE CL2C biometric NFT mint node for n8n — manually execute mints or expose Mint Biometric NFT as an AI Agent tool.

The node is a thin gate to the CL2C API: resolve owner → create NFT → poll until MINTED or FAILED → return agent-readable JSON. Confida biometric approval happens on the owner's mobile device after create; this package does not embed the Confida SDK.

Requirements: n8n ≥ 1.79.0 (community AI Agent tools).

Quick Start

Goal: first successful testnet mint in under 30 minutes.

1. Install the community node

On your n8n host, set environment variables:

N8N_COMMUNITY_PACKAGES_ENABLED=true
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true   # required for AI Agent tools

Restart n8n, then: Settings → Community Nodes → Install → enter n8n-nodes-taliware.

2. Create Taliware API credentials

In n8n: Credentials → New → Taliware API

The CL2C API has a single production host (https://developer.taliware.com/api/v1) — there is no separate testnet host, so this node no longer exposes a Base URL field. Testnet: Pick a smart contract where env is TESTNET (via CL2C API or TALIWARE platform). Set that UUID in credentials or override it on the node.

List contracts (example):

curl -s -H "x-api-key: YOUR_KEY" \
  "https://developer.taliware.com/api/v1/cl2c/contract?limit=50" | jq '.data[] | {id, name, env, network}'

3. Invite the NFT owner

The owner must exist on the TALIWARE platform before mint. Either:

• Platform UI — invite the user via the TALIWARE dashboard, or
• API — POST /cl2c/user with the owner's email:

curl -s -X POST "https://developer.taliware.com/api/v1/cl2c/user" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@example.com"}'

The owner must complete Confida setup (see below) before mint can succeed.

Owner User ID: When resolving by email, the node uses the org entry id from GET /cl2c/user (UUID), not the nested user.id platform identifier. You can paste that UUID into Owner User ID to skip email lookup:

curl -s -H "x-api-key: YOUR_KEY" \
  "https://developer.taliware.com/api/v1/cl2c/user?search=owner@example.com" | jq '.data[] | {id, email, status}'

Use the top-level id field in the mint request.

4. Run your first manual mint

1. Add Mint Biometric NFT to a workflow.
2. Select Taliware API credentials.
3. Set parameters:
   • Owner Email (or Owner User ID)
   • Name (optional — leave empty to auto-generate a unique name like Taliware NFT 3f9a1c2b)
   • Image Path — HTTPS URL, base64 (data:image/...;base64,... or raw), or leave empty and pass binary on the input item (see Binary Property Name)
   • Smart Contract ID — leave empty to use credential default, or paste a TESTNET contract UUID
4. Click Execute workflow.
5. The owner receives a Confida mobile notification — complete fingerprint approval on device.
6. The node polls until status is MINTED or FAILED (default: 10 s interval, 20 min timeout).

On success, output includes status: "MINTED", mintedAt, and smartContract.contractAddress.

Mint from a local file: Import workflows/manual-mint-binary.example.json — Read Binary File (set filePath to your PNG/JPEG) → Mint Biometric NFT with Image Path empty and Binary Property Name data.

If Confida confirms but the node ends with status: FAILED and mintedAt: null, the create + IPFS + biometric steps succeeded; on-chain mint likely failed (e.g. unfunded org wallet / CRDB tokens). Retry after TALIWARE recharges testnet funds — no node change required.

Confida (biometric approval)

TALIWARE orchestrates Confida for biometric identity verification. This node does not embed the Confida SDK or capture biometrics inside n8n.

What happens:

1. Owner is invited to the platform and completes Confida setup on mobile.
2. POST /cl2c/nft creates the NFT with status: CREATED and triggers Confida notifications.
3. Owner approves on mobile (fingerprint).
4. This node polls GET /cl2c/nft/{id} until terminal status.

If the owner ignores the notification, polling hits the timeout — see ConfidaTimeout in Error Reference.

Full Confida documentation: developer.taliware.com/docs/confida

AI Agent tool

Connect the tool

1. Confirm env vars from Quick Start are set.
2. Add an AI Agent node to your workflow.
3. On the agent's Tools input, add Mint Biometric NFT Tool (the wrapped variant of this node).
4. Select credentials and configure poll/debug settings on the tool node if needed.

Agent-supplied parameters (via $fromAI when the tool is connected):

The NFT name is not requested from the agent: it is auto-generated per mint (or set the Name field to a fixed value).

Manual Execute and Tool invoke share the same execute() code path.

Tool output fields (for agent prompts)

On MINTED, the tool returns a single JSON item (under ~8 KB, no raw image bytes):

{
  "id": "uuid",
  "status": "MINTED",
  "name": "My Photo NFT",
  "description": "…",
  "imagePath": "https://…",
  "externalUrl": "https://…",
  "mintedAt": "2026-05-30T12:00:00.000Z",
  "smartContract": {
    "id": "uuid",
    "contractAddress": "0x…",
    "env": "TESTNET",
    "network": "cordoba"
  },
  "copyright": [
    {
      "email": "owner@example.com",
      "status": "…",
      "percentage": 100,
      "walletAddress": "0x…"
    }
  ]
}

Use id, status, mintedAt, smartContract.contractAddress, and copyright[] in agent system prompts so the model can confirm mint success to the user.

Workflow Tool workaround (n8n #26202)

Some n8n versions have a FIFO queue ordering bug where AI Agents receive an empty observation from usableAsTool community nodes even though the tool executed successfully.

Symptom: Agent says the tool returned nothing; execution log shows the mint node succeeded with JSON output.

Workaround: Wrap the mint in a sub-workflow and connect it via n8n's native Workflow Tool (uses supplyData, not the usableAsTool wrapper):

1. Create a workflow with Execute Workflow Trigger (or When Executed by Another Workflow) → Mint Biometric NFT → return mapped JSON.
2. In your agent workflow, add Workflow Tool pointing at that sub-workflow instead of Mint Biometric NFT Tool directly.
3. Map tool inputs in the sub-workflow trigger to mint node parameters.

Upgrade n8n when a fix for #26202 is available in your release channel.

Taliware Agent (biometric-gated AI agent)

Taliware Agent is an AI agent node whose sensitive tools run only after the owner approves the exact action with their fingerprint in Confida. Enforcement is in the node's code, not in the LLM: the model can ask for a sensitive tool, but it never runs unless the TALIWARE API reports the approval.

Taliware Agent ── Chat Model (required)
               ── Memory (optional)
               ── Tools ── Search, Calendar                → run freely
               ── Tools ── Taliware Auth                   → biometric gate
                             └─ Tool ── Pay invoice, Delete record

1. Add Taliware Agent and connect a Chat Model (and optionally Memory).
2. Connect normal tools directly to its Tools port.
3. Add a Taliware Auth node, set the Approver Email (or User ID) and credentials, and connect it to the agent's Tools port.
4. Connect every sensitive tool to Taliware Auth, never directly to the agent.

When the model calls a gated tool, Taliware Auth creates an approval request (a mint with no image) and waits for the approver's decision, 5 minutes by default. Approved: the tool runs once, with the exact arguments that were approved. Rejected, timed out or failed: the tool does not run and the model is told.

The node output contains output (the agent's reply) and approvals[]: tool, decision (APPROVED, REJECTED, TIMED_OUT, FAILED), actionHash, requestId, approvedBy, approvedAt, location.

Setup rules

• Never connect the same capability both through Taliware Auth and directly; the agent refuses to start if the same tool name appears on both.
• The approver is fixed in the node on purpose: the AI can never choose who approves.
• Each approval request is a real mint (CRDB and gas); Max Approvals Per Run caps them per execution.
• Approval requests are recorded publicly on IPFS like any mint, including the approver's identity and location.

Error Reference

All failures use NodeOperationError with a prefix in the execution log:

Example messages:

• Validation: Owner not found — user must be invited via TALIWARE platform or POST /cl2c/user
• Validation: imagePath must be an HTTPS URL, a data:image/...;base64,... URI, or raw base64 image data
• ConfidaTimeout: Mint approval timed out — Confida biometric approval may still be pending (id=…, status=CREATED). Do not retry this request — CL2C has no idempotency key, and a retry creates a new NFT and a new approval request instead of resuming this one. Ask the owner to approve on their phone; this mint may still complete on its own.

Reliability

Duplicate mint on agent retries

CL2C v1.0.0 has no idempotency key. If an AI Agent retries a failed or timed-out tool call, each attempt creates a new NFT via POST /cl2c/nft. Design agent prompts and error handling to avoid blind retries after partial success (e.g. after create but before poll completes).

HTTP 429 rate limits

The CL2C client retries up to 3 times with exponential backoff (1 s, 2 s, 4 s) on HTTP 429.

Poll behaviour

The node polls until NFT-level status is MINTED or FAILED. Success is determined by status === 'MINTED', not individual copyright[].status values. Defaults: 10 s interval, 20 min timeout (configurable on the node).

Debug mode

Enable Debug on the node to log NFT id, poll count, and last status only — never API keys or full email addresses.

Publishing

Version 0.1.0 is published to npm as n8n-nodes-taliware.

Local checks before release

npm run lint
npm run build
npm pack --dry-run   # verify tarball: dist/, workflows/, README, LICENSE, CHANGELOG only

The package files field includes only dist/ and workflows/ — no BMad or planning artifacts are shipped.

Release to npm (with provenance)

1. Configure npm Trusted Publishing (OIDC) on npmjs.com for this repo's publish.yml workflow, or set NPM_TOKEN in GitHub secrets.

2. Locally bump and tag (does not publish from your machine):

   npm run release
   

3. Push the tag (e.g. 0.1.0) — GitHub Actions runs .github/workflows/publish.yml, which lint/builds and runs npm publish with NPM_CONFIG_PROVENANCE=true.

Example workflows for post-publish validation are in workflows/.

Development

Requirements: Node.js ≥ 22.16 (n8n engine), npm. For local npm run dev with bundled n8n, Node 22 LTS is recommended — Node 24 may fail on native isolated-vm builds.

cd n8n-nodes-taliware
npm install          # uses .npmrc ignore-scripts=true for @n8n/node-cli
npm run build
npm run lint
npm run dev          # symlinks to ~/.n8n-node-cli and starts n8n + tsc watch

Local n8n test (while testnet tokens recharge)

1. npm run build && npm run dev (or docker compose up after build).
2. Open http://localhost:5678 → Credentials → Taliware API:
   • API Key: your n8nplugin… CL2C key (x-api-key, not Bearer)
   • Default Smart Contract ID: TESTNET contract UUID
3. Import workflows/manual-mint-binary.example.json.
4. Set Read Binary File → filePath to a local image (e.g. scripts/fixtures/testest.png during dev).
5. Set Owner Email to a Confida-ready ACTIVE user; leave Image Path empty.
6. Execute → approve Confida on mobile → node polls until MINTED or FAILED.

See scripts/README.md for curl smoke tests without n8n.

External n8n:

# Terminal 1
npm run dev -- --external-n8n

# Terminal 2
N8N_DEV_RELOAD=true N8N_USER_FOLDER=$HOME/.n8n-node-cli n8n start

Resources

• CL2C OpenAPI spec (cl2c.yaml)
• Confida documentation
• n8n community nodes
• n8n $fromAI() function