Skip to main content

Tokens

Use the Tokens endpoint(s) to retrieve TestMachine custody-risk analysis for an ERC-20 token contract.

Base URL​

All API endpoints are relative to:

https://api.testmachine.ai

What you provide​

A token analysis request is identified by:

  • Network — where the contract is deployed (see Supported networks)
  • Token contract address — the ERC-20 contract address (checksummed or lowercase 0x…)

Response shape​

A successful response returns a token record and its detected custody-risk behaviors.

For definitions of each behavior identifier returned by the API, see Behaviors.

Fields​

  • id — internal token record identifier
  • address — token contract address
  • network_id — network identifier as an EVM chain ID (for example 1 for Ethereum mainnet, 8453 for Base)
  • name — token name (if available)
  • symbol — token symbol (if available)
  • monitoring_enabled — whether monitoring is enabled for this token in your account
  • created_at — ISO 8601 timestamp (UTC) when the token record was created
  • updated_at — ISO 8601 timestamp (UTC) when the token record was last updated
  • last_analyzed — ISO 8601 timestamp (UTC) of the most recent completed analysis
  • has_successful_analysis — whether at least one analysis run has completed successfully
  • behaviors — list of detected custody-control / privileged-capability categories

Example response​

{
  "id": 77,
  "address": "0x85483696cc9970ad9edd786b2c5ef735f38d156f",
  "network_id": 8453,
  "name": "USDC+",
  "symbol": "USDC+",
  "monitoring_enabled": true,
  "created_at": "2025-08-25T15:12:47.045707Z",
  "updated_at": "2025-08-25T15:12:47.045707Z",
  "last_analyzed": "2025-11-07T16:26:21.246707Z",
  "has_successful_analysis": true,
  "behaviors": [
    "confiscation",
    "pause",
    "upgrade",
    "management",
    "transfer_fee_reconfiguration",
    "mint",
    "external_call"
  ]
}

Retrieve token analysis​

This documentation assumes a token lookup endpoint exists that takes a network identifier and token address.

To confirm the exact request path and parameters for your environment, share the request example you're using (method + URL + params) and we'll update this section to match it exactly.

Common errors​

  • 400 Bad Request — invalid network identifier or malformed address
  • 404 Not Found — token not found or not supported on that network
  • 401 Unauthorized / 403 Forbidden — authentication/authorization issues

See Errors.

Notes​

  • Determinism: analyses may change over time as contracts upgrade, new implementations are detected, or heuristics improve.
  • Caching: some accounts/environments may cache analysis responses for performance.

If your integration depends on strict reproducibility (for example "analyze at block N"), confirm whether your environment supports block-pinned analysis.