Chainy API Documentation

REST API for wallet risk assessment, deposit AML checks, USDT transfer monitoring, and self-service dynamic risk models.

Authentication

External partner API requests require an API key passed in the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" https://app.chainysoft.io/api/external/balance

Personal Dashboard self-service endpoints require your dashboard session token in the X-Token header.

curl -H "X-Token: YOUR_SESSION_TOKEN" https://app.chainysoft.io/api/v1/risk-models

API keys can be generated in your Personal Dashboard under the "API Keys" section, and risk model self-service is available in the "Risk Models" section.

Base URL
https://app.chainysoft.io
Endpoints
Wallet Checks
Account
USDT Transfers
Deposit Checks (AML/KYT)
External Risk Models
Dashboard Self-Service Risk Models

Wallet Checks

POST /api/external/checks/create

Create a wallet address risk check. The check is processed synchronously — the response includes the full risk analysis result.

Request Body
Parameter Type Required Description
address string required Wallet address to check
network string required Blockchain network: eth, bsc, btc, trx, ltc
Example Request
curl -X POST https://app.chainysoft.io/api/external/checks/create \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28", "network": "eth"}'
Response
{
  "status": true,
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "network": "eth",
    "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd28",
    "status": "COMPLETED",
    "riskLevel": "low",
    "riskScore": 5,
    "risks": [],
    "appliedRiskModel": {
      "code": "greengage_wallet_v1",
      "name": "Greengage Wallet Policy",
      "version": 2
    },
    "riskEngine": {
      "mode": "dynamic",
      "checkType": "wallet"
    },
    "decisionSummary": {
      "score": 5,
      "decision": null,
      "threatLevel": "low",
      "topContributors": []
    },
    "checkUrl": "https://app.chainysoft.io/check-details.html?uuid=a1b2c3d4..."
  },
  "balance": {
    "previous": 100.00,
    "current": 80.00,
    "charged": 20.00
  }
}
Error Codes
400 Missing address or network
402 Insufficient balance
404 User not found
GET /api/external/checks/:uuid

Get the result of a previously created wallet check by its UUID.

Path Parameters
uuid required UUID returned from the create check endpoint
Example Request
curl https://app.chainysoft.io/api/external/checks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "status": true,
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "network": "eth",
    "address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd28",
    "status": "COMPLETED",
    "riskLevel": "low",
    "riskScore": 5,
    "risks": [],
    "appliedRiskModel": {
      "code": "greengage_wallet_v1",
      "name": "Greengage Wallet Policy",
      "version": 2
    },
    "riskEngine": {
      "mode": "dynamic",
      "checkType": "wallet"
    },
    "decisionSummary": {
      "score": 5,
      "decision": null,
      "threatLevel": "low",
      "topContributors": []
    }
  }
}
Error Codes
403 Check belongs to another user
404 Check not found
GET /api/external/checks/list

List all your wallet checks with pagination.

Query Parameters
Parameter Type Default Description
limit integer 100 Number of results per page
offset integer 0 Offset for pagination
status string — Filter by status: NEW, PROCESSING, COMPLETED
Response
{
  "status": true,
  "data": {
    "checks": [
      {
        "uuid": "a1b2c3d4-...",
        "address": "0x742d35cc...",
        "network": "eth",
        "status": "COMPLETED",
        "checkType": "address",
        "createdAt": "2026-02-12T10:00:00.000Z",
        "checkUrl": "https://app.chainysoft.io/check-details.html?uuid=..."
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 100,
      "offset": 0,
      "hasMore": false
    }
  }
}

Account

GET /api/external/balance

Get your current account balance and pricing info.

Example Request
curl https://app.chainysoft.io/api/external/balance \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "status": true,
  "data": {
    "email": "user@example.com",
    "balance": "80.00",
    "pricePerCheck": "20.00",
    "checksRemaining": 4
  }
}

USDT Transfers

POST /api/external/usdt-transfers

Get USDT transfer history for a wallet address, including totals for sent, received, and net balance.

Request Body
Parameter Type Required Description
address string required Wallet address
network string required Network: eth, bsc, trx
limit integer optional Max transfers to return (default: 50)
Response
{
  "status": true,
  "data": {
    "address": "0x...",
    "network": "ETH",
    "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "transfers": [
      {
        "hash": "0xabc...",
        "from": "0x111...",
        "to": "0x222...",
        "valueUsdt": 1000.50,
        "timestamp": 1700000000
      }
    ],
    "stats": {
      "total": 25,
      "totalSent": "5000.00",
      "totalReceived": "12000.00",
      "netBalance": "7000.00"
    }
  }
}

Deposit Checks (AML/KYT)

Register incoming deposit transactions for automated AML/KYT verification. The system analyzes transaction risk, counterparty exposure, and makes an automated decision (ALLOW / HOLD / REJECT).

POST /api/external/deposit-checks

Register a deposit transaction for AML/KYT check. Processing starts automatically.

Request Body
Parameter Type Required Description
network string required Network: ETH, BSC, TRX
tx_hash string required Transaction hash
deposit_address string required Your deposit wallet address
token_id string optional Token contract address (for USDT, etc)
amount number optional Transaction amount
Example Request
curl -X POST https://app.chainysoft.io/api/external/deposit-checks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "ETH",
    "tx_hash": "0xabc123...",
    "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "token_id": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "amount": 1500.00
  }'
Response
{
  "status": true,
  "data": {
    "uuid": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "network": "ETH",
    "tx_hash": "0xabc123...",
    "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "token_id": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "kyt_status": "REGISTERED",
    "decision": "PENDING",
    "createdAt": "2026-02-12T10:00:00.000Z",
    "appliedRiskModel": {
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "version": 2
    },
    "riskEngine": {
      "mode": "dynamic",
      "checkType": "deposit"
    },
    "decisionSummary": {
      "score": null,
      "decision": "PENDING",
      "threatLevel": null,
      "topContributors": []
    }
  },
  "already_exists": false
}
GET /api/external/deposit-checks/:uuid

Get deposit check result. If the check is still PENDING, a background recheck is triggered automatically.

Path Parameters
uuid required UUID of the deposit check
Response (Completed)
{
  "status": true,
  "data": {
    "uuid": "b2c3d4e5-...",
    "network": "ETH",
    "tx_hash": "0xabc123...",
    "deposit_address": "0x742d35Cc...",
    "kyt_status": "DONE",
    "decision": "ALLOW",
    "risk_score": 8,
    "decision_reason": "Low risk transaction",
    "appliedRiskModel": {
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "version": 2
    },
    "riskEngine": {
      "mode": "dynamic",
      "checkType": "deposit"
    },
    "decisionSummary": {
      "score": 8,
      "decision": "ALLOW",
      "threatLevel": "low",
      "topContributors": [],
      "thresholds": {
        "holdMin": 50,
        "rejectMin": 80
      }
    },
    "result": {
      "risks": [...],
      "exposure": {...},
      "counterparty": {...}
    }
  },
  "is_complete": true
}
Possible Decisions
ALLOW Transaction is safe, proceed with deposit
HOLD Elevated risk, manual review recommended
REJECT High risk, do not process deposit
PENDING Check still in progress
GET /api/external/deposit-checks

List all your deposit checks with pagination and optional decision filter.

Query Parameters
Parameter Type Default Description
limit integer 100 Max results per page
offset integer 0 Pagination offset
decision string — Filter: ALLOW, HOLD, REJECT, PENDING
Response
{
  "status": true,
  "data": {
    "deposits": [
      {
        "uuid": "b2c3d4e5-...",
        "network": "ETH",
        "tx_hash": "0xabc123...",
        "deposit_address": "0x742d35Cc...",
        "kyt_status": "DONE",
        "decision": "ALLOW",
        "risk_score": 8,
        "createdAt": "2026-02-12T10:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 100,
      "offset": 0,
      "hasMore": true
    }
  }
}

External Risk Models

These endpoints let API clients inspect the currently applied risk model and run model-aware simulations with the same API key used for AML checks.

GET /api/external/risk-models/current

Return the currently resolved risk model for the authenticated API key. If checkType is omitted, the response includes both wallet and deposit resolutions.

Query Parameters
Parameter Type Required Description
checkType string optional wallet or deposit. Aliases address and transaction are accepted.
Example Request
curl "https://app.chainysoft.io/api/external/risk-models/current?checkType=deposit" \
  -H "X-API-Key: YOUR_API_KEY"
Response
{
  "status": true,
  "data": {
    "model": {
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "version": 2,
      "description": "Custom deposit policy for Greengage"
    },
    "scope": {
      "type": "api_key_id",
      "value": "current"
    },
    "engineMode": "dynamic",
    "supportedCheckTypes": ["wallet", "deposit"]
  }
}
POST /api/external/risk-models/simulate

Run a stateless simulation against the currently resolved risk model for the API key.

Request Body
Parameter Type Required Description
checkType string required wallet or deposit
payload object required Simulation input. For deposits use providerRiskScore, risks, directInteraction, indirectInteraction, counterpartyExposure, deepExposure, and customLabelMatches. For wallets use providerRiskScore (or riskScore), risks, deepExposure, and customLabelMatches.
Example Request
curl -X POST https://app.chainysoft.io/api/external/risk-models/simulate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkType": "deposit",
    "payload": {
      "directInteraction": [
        { "category": "sanctions", "risk_level": "high", "value_share": 1 }
      ]
    }
  }'
Response
{
  "status": true,
  "data": {
    "appliedRiskModel": {
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "version": 2
    },
    "riskEngine": {
      "mode": "dynamic",
      "checkType": "deposit"
    },
    "result": {
      "score": 90,
      "decision": "REJECT",
      "threatLevel": null
    },
    "decisionSummary": {
      "score": 90,
      "decision": "REJECT",
      "threatLevel": null,
      "topContributors": [
        {
          "category": "sanctions",
          "source": "direct_interaction",
          "score": 90
        }
      ],
      "thresholds": {
        "holdMin": 50,
        "rejectMin": 80
      }
    }
  }
}

Dashboard Self-Service Risk Models

These endpoints power the Personal Dashboard “Risk Models” section and require the dashboard session token in X-Token. They let account owners create tenant models, clone templates, bind models to their own API keys, simulate changes, and activate drafts.

Quick start flow
  1. Open a template or start from a blank draft in the dashboard.
  2. Set name, code, and description so the model is identifiable before scoring changes.
  3. Edit thresholds, categoryRules, levelRules, and save them.
  4. Run at least one wallet and/or deposit simulation to verify the decision output.
  5. Bind the draft to an API key or check type, then activate it for future traffic.
GET /api/v1/risk-models family

The dashboard exposes these catalog endpoints:

Endpoint Description
GET /api/v1/risk-models List your tenant-owned models
GET /api/v1/risk-models/templates List active system templates available for cloning
GET /api/v1/risk-models/api-keys List your active API keys available for model bindings
GET /api/v1/risk-models/:id Load model metadata, scopes, and rules
PATCH /api/v1/risk-models/:id Update draft metadata such as name, code, or description
Example Response: GET /api/v1/risk-models
{
  "status": true,
  "data": [
    {
      "id": "0d74bf0d-...",
      "code": "greengage_wallet_v1",
      "name": "Greengage Wallet Policy",
      "description": "Tenant-owned wallet model",
      "status": "draft",
      "version": 1,
      "isDefault": false,
      "ownerUserId": 125,
      "visibility": "tenant",
      "scopeCount": 1,
      "scopes": [
        {
          "id": "d5a3...",
          "scopeType": "api_key_id",
          "scopeValue": "17",
          "priority": 10,
          "executionMode": "dynamic",
          "isEnabled": true
        }
      ]
    }
  ]
}
GET /api/v1/risk-models/current

Resolve the currently active model for one of your API keys.

Query Parameters
Parameter Type Required Description
apiKeyId string optional One of your active API key ids. If omitted, the first active key is used.
checkType string optional wallet or deposit (default: wallet)
Example Request
curl "https://app.chainysoft.io/api/v1/risk-models/current?apiKeyId=17&checkType=deposit" \
  -H "X-Token: YOUR_SESSION_TOKEN"
Response
{
  "status": true,
  "data": {
    "apiKeyId": "17",
    "model": {
      "id": "0d74bf0d-...",
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "status": "active",
      "version": 2,
      "visibility": "tenant"
    },
    "scope": {
      "scopeType": "api_key_id",
      "scopeValue": "17",
      "priority": 10,
      "executionMode": "dynamic"
    },
    "executionMode": "dynamic"
  }
}
POST /api/v1/risk-models

Create a new tenant draft model. To clone an existing template or model, use POST /api/v1/risk-models/:id/clone.

Example Request
curl -X POST https://app.chainysoft.io/api/v1/risk-models \
  -H "X-Token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Greengage Deposit Policy",
    "code": "greengage_deposit_v1",
    "description": "Tenant-owned deposit policy"
  }'
Clone Example
curl -X POST https://app.chainysoft.io/api/v1/risk-models/CHAINY_TEMPLATE_ID/clone \
  -H "X-Token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Greengage Deposit Policy",
    "code": "greengage_deposit_v1"
  }'
PUT /api/v1/risk-models/:id/rules

Load and update thresholds, meta rules, level rules, and category rules for a draft model. Active models are read-only and must be cloned first.

Example Request
curl -X PUT https://app.chainysoft.io/api/v1/risk-models/RISK_MODEL_ID/rules \
  -H "X-Token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholds": {
      "deposit": { "holdMin": 40, "rejectMin": 75 }
    },
    "categoryRules": {
      "deposit": [
        {
          "categoryCode": "sanctions",
          "directWeight": 90,
          "indirectWeight": 90,
          "counterpartyWeight": 90,
          "customLabelWeight": 0,
          "isEnabled": true
        }
      ]
    },
    "levelRules": {
      "deposit": [
        { "providerRiskLevel": "high", "baseScore": 75 },
        { "providerRiskLevel": "severe", "baseScore": 95 }
      ]
    }
  }'
Response
{
  "status": true,
  "data": {
    "thresholds": {
      "wallet": { "id": "...", "checkType": "wallet", "holdMin": 50, "rejectMin": 75 },
      "deposit": { "id": "...", "checkType": "deposit", "holdMin": 40, "rejectMin": 75 }
    },
    "categoryRules": {
      "wallet": [],
      "deposit": [
        {
          "id": "...",
          "checkType": "deposit",
          "categoryCode": "sanctions",
          "directWeight": 90,
          "indirectWeight": 90,
          "counterpartyWeight": 90,
          "customLabelWeight": 0,
          "isEnabled": true
        }
      ]
    },
    "levelRules": {
      "wallet": [],
      "deposit": [
        { "id": "...", "checkType": "deposit", "providerRiskLevel": "high", "baseScore": 75 },
        { "id": "...", "checkType": "deposit", "providerRiskLevel": "severe", "baseScore": 95 }
      ]
    },
    "metaRules": {
      "wallet": null,
      "deposit": {
        "id": "...",
        "checkType": "deposit",
        "aggregationMode": "max_contribution",
        "deepExposureWeight": 0,
        "baseScoreWeight": 1
      }
    }
  }
}
POST /api/v1/risk-models/:id/scopes

Bind a draft model to one of your own API keys or to a specific check type. Existing scopes can be listed with GET /api/v1/risk-models/:id/scopes and removed with DELETE /api/v1/risk-model-scopes/:id.

Example Request
curl -X POST https://app.chainysoft.io/api/v1/risk-models/RISK_MODEL_ID/scopes \
  -H "X-Token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopeType": "api_key_id",
    "scopeValue": "17",
    "priority": 10,
    "executionMode": "dynamic",
    "isEnabled": true
  }'
Response
{
  "status": true,
  "data": {
    "id": "d5a3...",
    "riskModelId": "0d74bf0d-...",
    "scopeType": "api_key_id",
    "scopeValue": "17",
    "priority": 10,
    "executionMode": "dynamic",
    "isEnabled": true
  }
}
POST /api/v1/risk-models/:id/simulate

Simulate a draft or template model before activation.

Example Request
curl -X POST https://app.chainysoft.io/api/v1/risk-models/RISK_MODEL_ID/simulate \
  -H "X-Token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkType": "deposit",
    "payload": {
      "directInteraction": [
        { "category": "sanctions", "risk_level": "high", "value_share": 1 }
      ]
    }
  }'
Response
{
  "status": true,
  "data": {
    "checkType": "deposit",
    "model": {
      "id": "0d74bf0d-...",
      "code": "greengage_deposit_v1",
      "name": "Greengage Deposit Policy",
      "version": 1
    },
    "score": 90,
    "decision": "REJECT",
    "threatLevel": null,
    "trace": {
      "mode": "dynamic"
    }
  }
}
POST /api/v1/risk-models/:id/activate

Activate a tenant draft model. Activation affects new checks only. If the model has active scopes, the same scopes are removed from other active tenant models of the same owner.

Example Request
curl -X POST https://app.chainysoft.io/api/v1/risk-models/RISK_MODEL_ID/activate \
  -H "X-Token: YOUR_SESSION_TOKEN"

Risk Score Reference

Score Range Level Description
0 — 10 Low Clean wallet, no suspicious activity detected
10 — 25 Minor Some indirect exposure to risky entities
25 — 50 Medium Significant risk exposure, manual review recommended
50 — 75 High High risk exposure, proceed with caution
75 — 100 Critical Direct links to sanctioned/criminal entities

Supported Networks

Code Network Wallet Check Deposit Check USDT Transfers
eth Ethereum ✅ ✅ ✅
bsc BNB Chain (BSC) ✅ ✅ ✅
trx Tron ✅ ✅ ✅
btc Bitcoin ✅ — —
ltc Litecoin ✅ — —