Contract Audit API: AI-Powered Smart Contract Risk Analysis

The Contracts API runs SURCHI’s AI audit engine against any token contract and returns a structured risk report. Each audit checks for common attack vectors and red flags — renounced ownership, active mint and freeze authorities, upgradeability, liquidity lock status, honeypot behaviour, and holder concentration — and synthesises the results into a single risk score alongside a human-readable AI summary. All contract endpoints require the read:contracts scope on your API key.

GET /v1/contracts//audit

Run a full AI audit on a smart contract and retrieve the complete risk report. Audits are cached for 5 minutes; repeated calls within that window return the cached result instantly.

Parameters

Parameter	Type	Required	Description
`address`	string	Yes (path)	The contract or token address to audit
`network`	string	Yes (query)	Network identifier: `ethereum`, `bnb`, `solana`, `polygon`, `base`, `avalanche`, or `arbitrum`

Example Request

curl -X GET "https://api.surchi.xyz/v1/contracts/TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA/audit?network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

const address = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';

const response = await fetch(
  `https://api.surchi.xyz/v1/contracts/${address}/audit?network=solana`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);
const data = await response.json();
console.log(data.data.risk_score);    // e.g. 15
console.log(data.data.ai_summary);   // plain-English summary

import requests

address = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'

response = requests.get(
    f'https://api.surchi.xyz/v1/contracts/{address}/audit',
    params={'network': 'solana'},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
audit = response.json()['data']
print(f"Risk level: {audit['risk_level']} ({audit['risk_score']}/100)")

Example Response

{
  "success": true,
  "data": {
    "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "network": "solana",
    "risk_score": 15,
    "risk_level": "low",
    "checks": {
      "ownership_renounced": true,
      "mint_authority": false,
      "freeze_authority": false,
      "upgradeable": false,
      "liquidity_locked": true,
      "liquidity_burned": false,
      "honeypot": false,
      "top_10_holder_pct": 22.1,
      "developer_wallet_pct": 3.2
    },
    "ai_summary": "Contract shows strong safety indicators with renounced ownership and locked liquidity. Holder distribution is healthy. No honeypot behavior detected.",
    "report_url": "https://surchi.xyz/audit/report/abc123"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "network": "solana",
    "latency_ms": 310,
    "cached": false
  }
}

Response Field Reference

Top-Level Audit Fields

Field	Type	Description
`address`	string	The audited contract address
`network`	string	Network the contract was audited on
`risk_score`	integer	Composite risk score from 0 (safest) to 100 (highest risk)
`risk_level`	string	Human-readable label: `very_low`, `low`, `medium`, `high`, `critical`
`ai_summary`	string	Plain-English summary of the audit findings generated by SURCHI’s AI engine
`report_url`	string	Link to the full interactive audit report on surchi.xyz

Risk Score Bands

Score Range	Risk Level	Meaning
0 – 15	`very_low`	Excellent safety indicators across all checks
16 – 35	`low`	Minor concerns; generally safe for interaction
36 – 60	`medium`	Moderate risk; proceed with caution
61 – 80	`high`	Significant red flags; high probability of rug or exploit
81 – 100	`critical`	Severe risk indicators; avoid interaction

`checks` Object Fields

Each field in the checks object represents an individual safety check. Boolean fields are true when the check passes in favour of safety unless otherwise noted.

Field	Type	Description
`ownership_renounced`	boolean	`true` if the contract owner has renounced ownership, preventing privileged modifications
`mint_authority`	boolean	`true` if an active mint authority exists — the developer can create new tokens at will
`freeze_authority`	boolean	`true` if an active freeze authority exists — the developer can freeze holder wallets
`upgradeable`	boolean	`true` if the contract is behind a proxy or otherwise upgradeable by the owner
`liquidity_locked`	boolean	`true` if the primary liquidity pool tokens are locked in a third-party locker
`liquidity_burned`	boolean	`true` if LP tokens have been sent to a burn address, permanently removing them
`honeypot`	boolean	`true` if the contract appears to prevent holders from selling — a honeypot pattern
`top_10_holder_pct`	number	Percentage of total supply held by the top 10 wallets (excluding burn addresses)
`developer_wallet_pct`	number	Percentage of total supply held by wallets linked to the deployer

A mint_authority: true result means the deployer retains the ability to inflate the token supply without limit. This is a critical risk factor for any token whose value depends on scarcity. Always cross-reference with developer_wallet_pct and liquidity_locked before proceeding.

If the AI audit engine is temporarily unavailable — for example during a model update — the endpoint returns HTTP 503 with error code AUDIT_UNAVAILABLE. You can retry safely after 30 seconds. See the Errors reference for retry guidance.

API Reference

SDK

Webhooks

Contract Audit API: AI-Powered Smart Contract Risk Analysis

GET /v1/contracts//audit

Parameters

Example Request

Example Response

Response Field Reference

Top-Level Audit Fields

Risk Score Bands

`checks` Object Fields

​GET /v1/contracts//audit

​Parameters

​Example Request

​Example Response

​Response Field Reference

​Top-Level Audit Fields

​Risk Score Bands

​checks Object Fields

GET /v1/contracts//audit

Parameters

Example Request

Example Response

Response Field Reference

Top-Level Audit Fields

Risk Score Bands

`checks` Object Fields