Skip to main content

​
Overview

The Token Security endpoint provides detailed security and restriction data for tokens on EVM chains. It analyzes the token contract to identify potential red flags, holding distributions, fee structures, and transfer limitations that may affect trading.

​
GET Method - Single Item Query

Retrieve security information for a single token.

​
Query Parameters

  • blockchain (required) — The blockchain identifier (e.g., evm:1, evm:56, ethereum, bsc)
  • address (required) — Token contract address

​
Usage Examples

curl -X GET "https://api.mobula.io/api/2/token/security?blockchain=evm:1&address=0xe538905cf8410324e03a5a23c1c177a474d59b2b"

​
Response Format

{
  "data": {
    "address": "0xe538905cf8410324e03a5a23c1c177a474d59b2b",
    "chainId": 1,
    "contractHoldingsPercentage": 2.5,
    "burnedHoldingsPercentage": 45.8,
    "buyFeePercentage": 5.0,
    "sellFeePercentage": 5.0,
    "maxWalletAmountRaw": "1000000000000000000000",
    "maxSellAmountRaw": "500000000000000000000",
    "maxBuyAmountRaw": "750000000000000000000",
    "maxTransactionAmountRaw": "500000000000000000000"
  }
}

​
Response Fields

​
Core Fields

  • address (string) — Token contract address (checksummed)
  • chainId (number) — Blockchain chain ID

​
Holdings Analysis

  • contractHoldingsPercentage (number | null) — Percentage of total supply held by the contract itself. High values (>10%) may indicate centralization risks or potential honeypot mechanisms.
  • burnedHoldingsPercentage (number | null) — Percentage of total supply sent to dead/burn addresses. Higher values generally indicate deflationary tokenomics.

​
Fee Structure

  • buyFee (number | null) — Fee percentage charged on buy transactions. Extracted from the token contract’s security configuration.
  • sellFee (number | null) — Fee percentage charged on sell transactions. Extracted from the token contract’s security configuration.

​
Transfer Restrictions (EVM Only)

These fields attempt to query various common function names used by contracts to restrict transfers:
  • maxWallet (string | null) — Maximum token balance an address can hold (in wei/smallest unit). Null if no restriction exists.
    • Common function names checked: _maxWalletToken, maxWalletToken, maxWallet, _maxWalletBalance, maxWalletAmount, _maxWalletSize, MaxWalletSize, _walletMax, maxWalletSize
  • maxSell (string | null) — Maximum amount that can be sold in a single transaction (in wei/smallest unit). Null if no restriction exists.
    • Common function names checked: maxSellTransactionAmount, maxSellAmount
  • maxBuy (string | null) — Maximum amount that can be bought in a single transaction (in wei/smallest unit). Null if no restriction exists.
    • Common function names checked: maxBuyTransactionAmount, maxBuyAmount, maxBuy
  • maxTxn (string | null) — Maximum transaction amount regardless of buy/sell direction (in wei/smallest unit). Null if no restriction exists.
    • Common function names checked: _maxTransactionAmount, _maxTxAmount, maxTransactionAmount, MaxTxAmount, maxTxnAmount, maxTrxnAmount

​
Chain Support

  • EVM Chains: Full support with all fields populated (when available)
  • Non-EVM Chains: Only buyFee and sellFee will be populated (if available from metadata). Other fields will return null.

​
Important Notes

  1. RPC Preference: This endpoint uses private RPCs when available for better reliability and performance.
  2. Null Values: Many fields may return null for legitimate reasons:
    • The token contract doesn’t implement the specific restriction
    • The function names don’t match common patterns
    • RPC call failed or timed out
    • Token is on a non-EVM chain
  3. Interpretation Guidelines:
    • High contractHoldingsPercentage (>10%): Potential centralization or honeypot risk
    • High burnedHoldingsPercentage: Generally positive, indicates deflationary supply
    • High fees (buyFee/sellFee >10%): May limit trading activity
    • Transfer restrictions (maxWallet, maxBuy, maxSell): Common anti-whale measures
  4. Performance: All RPC calls are executed in parallel for optimal response time.

​
Error Handling

The endpoint returns HTTP 400 for:
  • Missing or invalid blockchain parameter
  • Missing or invalid address parameter
  • Token not found in the system
Other fields gracefully degrade to null if specific data points cannot be retrieved.

​
Use Cases

  • Due Diligence: Automated security screening for new tokens
  • Trading Bots: Pre-trade validation to avoid tokens with restrictive mechanics
  • Portfolio Risk Analysis: Assess holdings for potential red flags
  • DeFi Integrations: Validate token compatibility with protocols
  • Community Tools: Display security badges or warnings for tokens