> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surchi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Audit API: AI-Powered Smart Contract Risk Analysis

> REST API endpoint to run AI-powered smart contract audits. Returns risk score, ownership data, mint/freeze authority, honeypot status, and AI summary.

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/{address}/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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/contracts/TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA/audit?network=solana" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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)")
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "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                         |

<Warning>
  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.
</Warning>

<Note>
  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](/developer/api/errors) reference for retry guidance.
</Note>