# Security & liquidity

> Realized buy and sell tax, simulated honeypot checks, contract flags and LP lock status for any Robinhood Chain token.

Source: https://crius.sh/docs/reference/security/

Is the token safe to trade, and can its liquidity be pulled?

Tax is measured from **real trades** (what the pool sent versus what the wallet received, which also catches Uniswap v4 hook taxes), backed by **simulation** of a real buy → transfer → sell sequence at the head block, and **static** checks of the contract. A fresh simulation on demand (`fresh=1`) costs 20 credits and needs the Starter plan or higher.

| Endpoint | Method | Plan | Credits |
|---|---|---|---|
| [Security checks](#security-checks) | `GET /v1/{chain}/token/{address}/security` | Anonymous | 1 |
| [Liquidity & locks](#liquidity-locks) | `GET /v1/{chain}/token/{address}/liquidity` | Free | 5 |

## Security checks

**GET** `/v1/{chain}/token/{address}/security`

**Plan:** Anonymous and above (no key needed) · **Cost:** 1 credit per call

Contract checks (ownership, mint, pause, blacklist, proxy, limits), realized and simulated buy/sell tax, honeypot verdict and, for v4 tokens, the pool hook's permissions and risk. `amount_usd` sets the simulated trade size (default 100).

> Realized tax (30 d), eth_simulateV1 buy → transfer → sell for V2-routed tokens, owner / proxy / capabilities / limits, hook risk, LP status, flags, score.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `amount_usd` | query | number | `100` | Simulated trade size in USD. |
| `fresh` | query | integer |  | `1` runs a new simulation now (Starter plan and up, 20 credits). |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/security" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/security", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/security",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

[Try it in the playground →](https://crius.sh/docs/playground/?op=GET%20%2Fv1%2F%7Bchain%7D%2Ftoken%2F%7Baddress%7D%2Fsecurity)

### Key response fields

- `risk` (`low` / `medium` / `high`) and `score` (0–100), plus `flags`
- `honeypot.is_honeypot`, `honeypot.selective` (only some wallets can sell), `honeypot.reason`
- `tax.buy_pct`, `tax.sell_pct` and their `source`; `tax.realized` (from real trades, with sample counts and the highest sell tax seen) and `tax.simulated`
- `tax_history`: every tax change with the block it took effect
- `contract`: ownership, mintable, pausable, blacklist, proxy / upgradeable, can change tax or limits
- `hook`: the v4 pool hook's name, permissions, capabilities and risk
- `liquidity.summary`: locked, burned and unlocked shares of LP

### Example response

Real response captured from the API (arrays trimmed to three items).

```json
{
  "data": {
    "contract": {
      "blacklist": false,
      "can_change_limits": false,
      "can_change_tax": false,
      "cooldown": false,
      "implementation": null,
      "is_proxy": false,
      "mintable": false,
      "owner": null,
      "ownership": "none",
      "pausable": false,
      "proxy_kind": null,
      "self_destruct": false,
      "trading_switch": false,
      "upgradeable": false,
      "verified": null
    },
    "flags": [
      "unverified"
    ],
    "honeypot": {
      "is_honeypot": false,
      "reason": null,
      "selective": false
    },
    "hook": {
      "address": "0xe5e702641ea86f4ae6cc3cdaed2b886f976be044",
      "capabilities": {
        "can_block_swaps": false,
        "can_gate_liquidity": false,
        "can_modify_liquidity_amounts": false,
        "can_modify_swap_amounts": true
      },
      "name": "PonsV2MemeHook",
      "permissions": [
        "beforeInitialize",
        "afterSwap",
        "afterSwapReturnDelta"
      ],
      "risk": [
        "can_modify_swap_amounts"
      ]
    },
    "known_asset": false,
    "limits": {},
    "liquidity": {
      "status": "partially_locked",
      "summary": {
        "burned_pct": 0,
        "locked_pct": 99.8934,
        "next_unlock_ts": null,
        "protocol_fee_pct": 0,
        "unlocked_in_wallets_pct": 0.106605,
        "weighting": "by pool liquidity_usd"
      }
    },
    "primary_dex": "uniswap_v4",
    "risk": "low",
    "score": 95,
    "tax": {
      "buy_pct": 2.99,
      "confidence": "high",
      "realized": {
        "buy_pct": 2.99,
        "by_wallet_class": {
          "dev_sell_pct": null,
          "others_sell_pct": 0
        },
        "last_sample_ts": 1792705534000,
        "max_sell_pct_seen": 96.64,
        "samples": {
          "buys": 2529,
          "sells": 1840
        },
        "sell_pct": 0,
        "window": "30d"
      },
      "sell_pct": 0,
      "simulated": null,
      "source": "realized",
      "transfer_pct": null
    },
    "tax_history": [
      {
        "from_block": 88385895,
        "pct": 0,
        "side": "buy"
      },
      {
        "from_block": 88387118,
        "pct": 0,
        "side": "sell"
      },
      {
        "from_block": 88461329,
        "pct": 3,
        "side": "buy"
      }
    ],
    "tax_history_total": 29,
    "tax_mode": "dynamic",
    "token": "0x7b8892cea949bc60d494681d1bc3ea96071ab0b8"
  },
  "meta": {
    "block": 95504416,
    "block_age_ms": 890,
    "block_ts": 1792712997000,
    "chain": "robinhood",
    "finalized_block": 95493649,
    "lag_ms": 24,
    "safe_block": 95497061,
    "simulation": "no V2 WETH pair: realized tax only"
  }
}
```

## Liquidity & locks

**GET** `/v1/{chain}/token/{address}/liquidity`

**Plan:** Free and above · **Cost:** 5 credits per call

Who owns the token's liquidity, per pool: burned, locked (which locker, until when, who can withdraw) or held by wallets. After an unlock the LP keeps being followed: withdrawn → to whom → removed or still held. Supported lockers include the Pons launch locker, UNCX v2/v3/v4, Team Finance, TitanLocker and HoodLock.

> V2 LP-token holders, V3/V4 position NFT owners, decoded locker events (UNCX, Team Finance, Titan, HoodLock, Pons).

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/liquidity" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/liquidity", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/liquidity",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```