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

| Field | Required | Notes | |-------|----------|-------| | API Key | Yes | Sent as x-api-key on CL2C requests only — never logged | | Base URL | No | Default: https://developer.taliware.com/api/v1 | | Default Smart Contract ID | No | UUID of a contract with env: TESTNET for testnet mints |

Testnet: Use the same API host. 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":"[email protected]"}'

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/[email protected]" | 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 (required)
   • 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):

| Parameter | Required | Notes | |-----------|----------|-------| | name | Yes | NFT display name | | description | No | Photo or artwork description | | imagePath | No | HTTPS URL or base64 image for MintRequest.imagePath | | ownerEmail | One of email/userId | Platform user email | | ownerUserId | One of email/userId | Org entry id from GET /cl2c/user; skips email lookup when set | | smartContractId | No | Overrides credential default | | ownershipPercentage | No | Default 100 |

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": "[email protected]",
      "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.

Error Reference

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

| Prefix | Likely cause | Remediation | |--------|--------------|-------------| | Configuration: | Invalid or missing API key, bad base URL, missing default smart contract when node override is empty | Verify Taliware API credentials; set Default Smart Contract ID or node Smart Contract ID | | Validation: | Missing name, missing owner email/userId, owner not found, invalid imagePath, CL2C 400/404 validation | Fix parameters before retry; invite owner via platform or POST /cl2c/user | | API: | CL2C request failed, NFT status: FAILED after poll | Read message and API details; check contract env, owner Confida status, image data/URL | | ConfidaTimeout: | Poll timeout — owner did not complete biometric approval in time | Ask owner to approve on mobile; increase Poll Timeout Minutes; node does not auto re-mint | | n8nTool: | n8n tool-layer issues (e.g. empty observation from #26202) | Use Workflow Tool workaround; upgrade n8n |

Example messages:

• Validation: Name is required
• 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)

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