API v1 — Transaction Firewall

Prefixo: https://api.nzochain.com/api/v1
Auth: header X-API-Key
Query opcional: lang=pt ou lang=en

Integração actual = REST. Não existe SDK oficial publicado (@nzochain/sdk / NzochainClient). Exemplos: Quickstart.

A v1 é aditiva face ao /api legado. Produtos novos devem usar v1.

Endpoints e scopes

Método	Path	Scope	Plano mínimo
`POST`	`/v1/wallets/risk`	`wallet.scan`	Free
`POST`	`/v1/contracts/risk`	`contract.scan`	Free
`POST`	`/v1/transactions/analyze`	`transaction.analyze`	Starter
`POST`	`/v1/transactions/simulate`	`transaction.analyze`	Starter + quota mensal
`POST`	`/v1/threats/check`	`threat.check`	Growth

Scope em falta → 403 { "error": "SCOPE_REQUIRED", "required": "…" }.
Feature fora do plano → 403 PLAN_UPGRADE_REQUIRED.

Wallet risk

{ "wallet": "0x...", "network": "ethereum" }

network: ethereum | bnb | polygon | arbitrum. Opcionais (DTO partilhado): forceRefresh, includeBlocked, requesterWallet.

Contract risk

{ "address": "0x...", "network": "ethereum" }

Analyze transaction

{
  "chainId": 1,
  "wallet": "0x...",
  "to": "0x...",
  "calldata": "0x095ea7b3...",
  "value": "0"
}

Simulate

{
  "wallet": "0x...",
  "network": "ethereum",
  "tx": { "to": "0x...", "data": "0x...", "value": "0" }
}

Simulação live exige Tenderly. Sem Tenderly (ou se a chamada live falhar), a API devolve análise estática / degradada. Quotas mensais de simulate: Free 0 · Starter 100 · Growth 2 000 · Business 10 000 · Enterprise por contrato (pilot-grade). Esgotada → 403 SIMULATION_QUOTA.

Threats

{ "address": "0x...", "domain": "exemplo-phishing.com" }

Contrato da resposta

Envelope típico:

{
  "success": true,
  "data": {
    "riskScore": 0,
    "riskLevel": "SAFE | CAUTION | HIGH | CRITICAL",
    "decision": "ALLOW | REVIEW | BLOCK",
    "reasons": ["frases humanas"],
    "meta": {}
  }
}

Mapeamento típico: CRITICAL/HIGH → BLOCK · CAUTION → REVIEW · SAFE → ALLOW.

cURL

curl -X POST "https://api.nzochain.com/api/v1/wallets/risk?lang=en" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"wallet":"0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234","network":"ethereum"}'

curl -X POST "https://api.nzochain.com/api/v1/transactions/analyze?lang=en" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"chainId":1,"wallet":"0x...","to":"0x...","calldata":"0x...","value":"0"}'

JavaScript `fetch`

const res = await fetch('https://api.nzochain.com/api/v1/wallets/risk?lang=en', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.NZOCHAIN_API_KEY,
  },
  body: JSON.stringify({
    wallet: '0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234',
    network: 'ethereum',
  }),
});
const { success, data } = await res.json();

Quotas de volume

Free: hard cap → 429 RATE_LIMIT
Pagos: overage faturado até 3× a quota; depois 429 HARD_CEILING

Ver Overview e Erros. Planos: B2B.

​Endpoints e scopes

​Wallet risk

​Contract risk

​Analyze transaction

​Simulate

​Threats

​Contrato da resposta

​cURL

​JavaScript fetch

​Quotas de volume

Endpoints e scopes

Wallet risk

Contract risk

Analyze transaction

Simulate

Threats

Contrato da resposta

cURL

JavaScript `fetch`

Quotas de volume