TestMachine Token Custody API

Base URL: https://api.testmachine.ai

Latest Version: v2.0.0

QUICK START GUIDE

Get threat detection running in under 5 minutes

The TestMachine Token Custody API provides programmatic access to analyze ERC-20 token contracts for custodial risks. This guide is hands-on, with explicit request/response JSON examples for seamless integration.

1. Authentication

All requests must include an API key. If you don't have a token, contact TestMachine support.

X-Api-Key: {YOUR_TOKEN}

2. Start a Token Scan

Endpoint:

POST https://api.testmachine.ai/scan

Request Body:

{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "chain_id": 1
}

Parameters:

• address – Token contract address
• chain_id – EVM chain ID (see supported chains)

Sample Response:

{
  "id": "nyxpzFghAtzfzAoZT",
  "status": "submitted"
}

This id is your scan identifier. Use it to poll for results.

3. Retrieve Scan Results

Endpoint:

GET https://api.testmachine.ai/scan/{scan_id}

Sample Response (Success):

Successful Response

{
  "id": "nyxpzFghAtzfzAoZT",
  "status": "completed",
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "chain_id": 1,
  "risks": {
    "blacklist": {
      "function": "blacklist(address)",
      "authority": "0x1234...abcd"
    },
    "minting": {
      "function": "mint(address,uint256)",
      "authority": "0xabcd...1234"
    }
  },
  "inherent_score": 5
}

Sample Response (Failure):

Failure Response

{
  "id": "nyxpzFghAtzfzAoZT",
  "status": "failed",
  "error": "Contract has no available ABI"
}

Response Fields:

• status – submitted, running, completed, or failed
• risks – Map of detected behaviors with function signatures and authorities
• inherent_score – Severity score (higher = riskier)

→ Complete response format documentation

4. Example Workflow with cURL

Submit Scan:

Submit Scan

curl -X POST \
  -H "X-Api-Key: {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chain_id": 1}' \
  https://api.testmachine.ai/scan

Check Results:

Check Results

curl -H "X-Api-Key: {YOUR_TOKEN}" \
  https://api.testmachine.ai/scan/nyxpzFghAtzfzAoZT

5. Supported Chains

Ethereum Mainnet 1

Base 8453

Arbitrum One 42161

OP Mainnet 10

Polygon 137

Avalanche C-Chain 43114

Sonic Mainnet 146

Additional EVM-compatible chains can be easily added. Contact TestMachine to discuss adding support for your specific chain.

6. Scan Timing and Limits

Typical scan time:

~70 seconds

Complex contracts:

up to 5 minutes

Hard timeout:

5 minutes per scan

Zero false positives:

If uncertain, results omitted

7. Common Failure Cases

A scan may fail if:

• No ABI or source code is available
• Contract does not conform to ERC-20 standard

• No prior transfer history exists
• Non-standard proxy patterns are detected

8. Integrating Into Your Systems

Onboarding Pipelines

Trigger scans on newly submitted token addresses

Monitoring

Use push-based monitoring for live updates across networks

Dashboards

Parse JSON results to display behaviors and severity scores

API REFERENCE

Direct access to TestMachine's threat detection engine

POST /scan

ACTIVE

Submit a smart contract for security analysis.

Request Parameters

contract_source	string	Required. Solidity source code
contract_name	string	Optional. Contract identifier
analysis_type	string	Optional. "quick" \| "full" \| "custodial"

Response

{
  "scan_id": "uuid-string",
  "status": "queued",
  "estimated_completion": "2024-01-15T10:30:00Z"
}

GET /scan/{scan_id}

ACTIVE

Retrieve analysis results for a completed job.

Response

{
  "scan_id": "uuid-string",
  "status": "completed",
  "vulnerabilities": [...],
  "risk_score": 7.2,
  "recommendations": [...],
  "completed_at": "2024-01-15T10:35:00Z"
}