@kyb-brasil/agent-tools

Brazilian company due diligence and prospecting as tools for AI agents. Name → CNPJ, Receita Federal registration, CGU sanctions, forced-labour list, PGFN federal debt, IBAMA environmental embargoes, economic group, OFAC/UN/EU screening, federal contracts, a deterministic 0-100 risk score, and prospecting lists by CNAE / state / city. Every answer is JSON with a summary in English and Portuguese and the source URL and date of each fact.

Paid per call with x402 (USDC on Base, no signup, no API key). Free tools work without a wallet. Errors are never charged.

The tools are built at runtime from the service's own /openapi.json, so new tools and prices show up without updating this package.

Install

npm i @kyb-brasil/agent-tools

Node 18+ (global fetch). ESM.

Quick start

import { createKybTools } from "@kyb-brasil/agent-tools";

// Free tools only (no wallet):
const kyb = await createKybTools();

// Paid tools too: a wallet holding a few USDC on Base (no ETH needed, the facilitator pays gas).
const kyb = await createKybTools({ privateKey: process.env.KYB_PAYER_PK as `0x${string}` });

const found = await kyb.execute("br_company_search", { query: "petrobras", state: "RJ" }); // free
const cnpj = found.results[0].cnpj;
const risk = await kyb.execute("br_risk_screen", { cnpj });                                 // 0.05 USDC
console.log(risk.risk.level, risk.risk.score, risk.summary.en);

Tools

| Tool | What it returns | Price (USDC) | |---|---|---| | br_company_search | Name → up to 20 active establishments (CNPJ, names, city/state, CNAE, opening date) | free | | br_company_check | Receita Federal registration: status, legal name, CNAE, size, age, address | free | | br_company_count | How many active establishments match a CNAE / state / city / date filter | free | | br_sanctions_screen | Company, branches and corporate partners against CEIS, CNEP, CEPIM, leniency and the forced-labour list, with evidence URLs | 0.03 | | br_risk_screen | Red flags only: status, sanctions, forced labour, federal debt and fiscal regularity, embargoes, OFAC/UN/EU, economic group, risk score, per-section data quality | 0.05 | | br_company_dossier | Everything: registration, ownership (no personal IDs), economic group, sanctions, debt, embargoes, federal contracts, BNDES, international lists, gazette mentions, risk score | 0.15 | | br_company_list | Prospecting: 100 active establishments per page for a CNAE / state / city / date filter, stable paging | 0.05 per page | | br_batch_sanctions | Up to 10 CNPJs, one payment | 0.25 | | br_batch_dossier | Up to 10 dossiers, one payment | 1.20 | | br_replay | Re-read any paid answer from the last 10 minutes with its receipt.replay_token | free |

Free tools are rate limited (50/day per IP). Prices are read from the service at runtime (kyb.tools[i].priceUsd).

Use with your framework

The adapters take the framework's own constructors as arguments, so this package has no framework dependency.

Vercel AI SDK

import { generateText, tool, jsonSchema } from "ai";
import { createKybTools, toVercelAI } from "@kyb-brasil/agent-tools";

const kyb = await createKybTools({ privateKey });
const { text } = await generateText({
  model,
  tools: toVercelAI(kyb, { tool, jsonSchema }),
  maxSteps: 6,
  prompt: "Is Construtora Alfa in Curitiba safe to onboard as a supplier? Check sanctions and debt."
});

LangChain

import { tool } from "@langchain/core/tools";
import { createKybTools, toLangChain } from "@kyb-brasil/agent-tools";

const kyb = await createKybTools({ privateKey });
const tools = toLangChain(kyb, tool); // StructuredTool[] with JSON schemas, ready for an agent

OpenAI function calling

import { createKybTools, toOpenAI } from "@kyb-brasil/agent-tools";

const kyb = await createKybTools({ privateKey });
const response = await openai.chat.completions.create({ model: "gpt-4.1", tools: toOpenAI(kyb), messages });
for (const call of response.choices[0].message.tool_calls ?? []) {
  const result = await kyb.execute(call.function.name, JSON.parse(call.function.arguments));
}

Anthropic Messages API

import { createKybTools, toAnthropic } from "@kyb-brasil/agent-tools";

const kyb = await createKybTools({ privateKey });
const msg = await anthropic.messages.create({ model, max_tokens: 1024, tools: toAnthropic(kyb), messages });
// for each tool_use block: await kyb.execute(block.name, block.input)

MCP clients (Claude, Cursor, etc.) do not need this package: connect to https://kyb-br-agents.marcelfons.workers.dev/mcp.

How payment works

1. The agent calls a paid tool. The service answers HTTP 402 with the price, the network (eip155:8453, Base) and the receiving address.
2. This package signs a USDC transfer authorization with your wallet key and retries; the Coinbase facilitator settles it on-chain. No ETH, no gas, no account anywhere.
3. The answer carries receipt.replay_token: if your process loses the response, call br_replay with the token within 10 minutes instead of paying again.

Fund the wallet with a few USDC on Base (Coinbase → Send → network Base). Keep it a dedicated low-balance wallet. Without privateKey, paid tools throw KybError with code: "PAYMENT_REQUIRED".

Proof of what was returned

Every paid answer carries attestation (Ed25519 signature over the canonical JSON of the answer, with sha256, signed_at, key_id). Keep the JSON and you can prove later what the service said and when:

import { verifyAttestation } from "@kyb-brasil/agent-tools";
const check = await verifyAttestation(risk); // fetches the public key from /.well-known/kyb-attestation.json
// { valid: true, key_id, signed_at }  or  { valid: false, reason: "content hash mismatch: the answer was modified" }

Red flags also carry action (what to do about it, in English and Portuguese) and risk.next_steps lists the actions in order of severity. Partners registered in tax-favoured jurisdictions (Receita Federal IN 1.037) come with tax_haven: true and the PARTNER_IN_TAX_HAVEN flag.

Portuguese tool descriptions: createKybTools({ baseUrl: "https://kyb-br-agents.marcelfons.workers.dev", lang: "pt" }) is not needed: pass the OpenAPI URL variant instead, baseUrl + /openapi.json?lang=pt, or use the MCP endpoint /mcp?lang=pt.

Errors

All failures throw KybError with code (INVALID_CNPJ, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, PAYMENT_REQUIRED) and status. Failed calls are never charged. When a data source is down, the dossier still answers, with the affected section as null and a code in warnings[]; data_quality[] tells the age of every section.

Options

createKybTools({
  baseUrl?: string,        // default: production
  privateKey?: `0x${string}`,
  internalKey?: string,    // platform partners: bypasses x402 through the internal channel
  include?: string[],      // keep only these tool names
  exclude?: string[],      // drop these (e.g. the batch tools)
  fetch?: typeof fetch
});
// kyb.tools: { name, description, priceUsd, parameters (JSON schema), execute }[]
// kyb.execute(name, args), kyb.byName, kyb.spec (the OpenAPI document)

kybToolsFromSpec(spec, options) builds the same from an OpenAPI document you already have (tests, offline).

Data and privacy

Official open data only: Receita Federal, CGU / Portal da Transparência, MTE, PGFN, IBAMA, BNDES, OFAC, UN, EU, Querido Diário. CPFs are never stored or returned (individual entrepreneurs' legal names are masked); sanctions are never matched against individuals. Not legal or compliance advice: verify critical facts at the source URLs in every answer.

Links

• Agent-readable docs: https://kyb-br-agents.marcelfons.workers.dev/llms.txt
• OpenAPI: https://kyb-br-agents.marcelfons.workers.dev/openapi.json
• Service status and data age: https://kyb-br-agents.marcelfons.workers.dev/status
• Example responses for every tool: https://github.com/celfons/kyb-brasil/tree/main/examples
• Terms: https://kyb-br-agents.marcelfons.workers.dev/terms

Contract policy: fields in /v1 are only added, never renamed or removed; breaking changes ship as /v2 with 90 days of overlap. MIT.