zkMe Agent Toolkit

Minimal SDK, CLI demo, and local MCP server for AI-readable zkMe developer integrations.

This package wraps existing zkMe public APIs. It does not add new AI-only business APIs, OAuth, database tables, hosted MCP services, or broader data permissions.

Supported P0 APIs

| SDK method | Existing endpoint | Purpose | |---|---|---| | client.kyt.status() | POST /openapi/kyt/status | Check KYT API availability. | | client.kyt.getRiskScore() | POST /openapi/kyt/risk/score | Get risk score for one address or transaction hash. | | client.kyc.getStatus() | POST /openapi/v2/queryKycInfoByAddress | Get KYC status for one account and program. |

Install

npm install @zkmelabs/agent-toolkit

For local source testing inside this repository:

cd agent-toolkit
npm install
npm run build
npm test

Configure

Set credentials in the runtime environment, not in prompts or source code.

export ZKME_API_BASE_URL="https://api.zk.me"
export ZKME_MCH_NO="your_merchant_no"
export ZKME_API_KEY="your_api_key"

For sandbox or test usage, use the API base URL provided by zkMe without the endpoint path:

export ZKME_API_BASE_URL="<zkme_sandbox_api_base_url>"

The SDK also signs POST requests for the zkMe gateway. Defaults are provided for the public developer gateway:

export ZKME_APP_VERSION="zkserapi_1.0.0"
export ZKME_APP_KEY="<provided by zkMe when a non-default gateway key is required>"

Most developers only need to set ZKME_API_BASE_URL, ZKME_MCH_NO, and ZKME_API_KEY.

SDK Example

import { ZkMeClient } from "@zkmelabs/agent-toolkit";

const client = new ZkMeClient();

const status = await client.kyt.status();
const risk = await client.kyt.getRiskScore({
  coin: "ETH",
  address: "0x0000000000000000000000000000000000000000"
});
const kyc = await client.kyc.getStatus({
  programNo: "202302170004",
  account: "0x0000000000000000000000000000000000000000",
  chainId: "137"
});

console.log({ status, risk, kyc });

CLI Demo

zkme-demo kyt-status
zkme-demo kyt-risk-score --coin ETH --address 0x0000000000000000000000000000000000000000
zkme-demo kyt-risk-score --coin ETH --txid 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
zkme-demo kyc-status --programNo 202302170004 --account 0x0000000000000000000000000000000000000000 --chainId 137

Dry-run mode validates command shape without calling zkMe APIs:

zkme-demo kyt-risk-score --coin ETH --address 0x0000000000000000000000000000000000000000 --dry-run

MCP Server

The local MCP server is implemented with the official @modelcontextprotocol/sdk and uses stdio transport.

Configure an MCP client to run the local stdio server:

{
  "mcpServers": {
    "zkme": {
      "command": "npx",
      "args": ["-y", "-p", "@zkmelabs/agent-toolkit", "zkme-mcp"],
      "env": {
        "ZKME_API_BASE_URL": "https://api.zk.me",
        "ZKME_MCH_NO": "your_merchant_no",
        "ZKME_API_KEY": "your_api_key"
      }
    }
  }
}

Available tools:

• zkme_docs_get
• zkme_kyt_status
• zkme_kyt_risk_score
• zkme_kyc_status_get

AI-readable Resources

Website/static deployment should expose:

• /llms-zkme-developers.txt
• /agents.md
• /openapi/zkme.openapi.json

In zkme-website, these paths are served by explicit controller mappings because default Spring static resource mappings are disabled.

The same files are mirrored in this package under docs/ so agents and developers can inspect them after npm installation.

Privacy Boundary

• Do not pass API keys as MCP tool arguments.
• Do not log or print ZKME_API_KEY.
• Do not request raw KYC documents, biometric data, face images, or verify raw data.
• Do not use the toolkit for bulk KYC user lists.
• All returned data remains scoped to the configured merchant credentials.