Back to top

API Documentation

From Global Ledger team

Welcome

Welcome, developers, to the API documentation for Global Ledger API. This documentation serves as an authoritative guide for harnessing the power of our universal endpoints across multiple blockchains. Within this documentation, you will find well-detailed information regarding each of our endpoints. We provide a transaction or address scoring in both native coins and tokens, as well as balance retrievals in the same denominations. We also furnish instructions for webhook integration, inclusive of steps on creating webhooks, adding an address to it, and managing it efficiently (namely updating and deletion operations). To aid understanding, we have provided examples reflecting both successful responses across multiple chains and negative responses alike for reference. We welcome your feedback and encourage you to reach out through our support channels if you have questions or suggestions about this documentation or our API services.

Happy coding!

Supported Blockchains

  • Bitcoin (BTC)

  • Litecoin (LTC)

  • Bitcoin Satoshi Vision (BSV)

  • Ethereum (ETH)

  • Tron (TRX)

  • Binance Smart Chain (BNB)

  • Avalanche (AVAX)

The blockchain is indicated in the subdomain as a ticker https://{ticker}.glprotocol.com/api/{endpoint}/{param}

Ticker

Ticker is a subdomain of the corresponding API.

  • blockchain tickers: btc|ltc|bsv|eth|tron|bnb|avax

  • system ticker: access.common|common

Response wrapper

Each request to API is encased within a standardized wrapper, as per the documentation guidelines.

  • Wrapper
    • success: (boolean) - true if request was successfully processed
    • data: {any} (any) - response payload
    • response.errors: {any} (any) - Error message. Only when success: false

Authorization

Use the x-api-key header with the value {API_KEY} for authentication.

You can obtain your {API_KEY} by visiting https://vision.glprotocol.com/profile.

Authentication Endpoint

Authentication Endpoint
POST/api-users/users/login

Authenticate users and obtain an access token for accessing other protected endpoints.

  • ticker: access.common - The subdomain to system services

Example URI

POST https://{ticker}.glprotocol.com/api-users/users/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "user@example.com",
  "password": "your_password"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "{User_ID}",
  "token": "{JWT_Bearer_Token}",
  "lang": "en",
  "refreshToken": "{JWT_Bearer_Refresh_Token}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The user's ID"
    },
    "token": {
      "type": "string",
      "description": "The bearer token."
    },
    "lang": {
      "type": "string",
      "description": "The language preference of the user."
    },
    "refreshToken": {
      "type": "string",
      "description": "The refresh token."
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "messageType": "BadRequestException",
  "message": "Invalid username or password!",
  "stack": "BadRequestException: INVALID_USERNAME\\n    at {STACK_TRACE}",
  "response": {
    "statusCode": 400,
    "message": "INVALID_USERNAME",
    "error": "Bad Request"
  },
  "status": 400,
  "name": "BadRequestException"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string",
      "description": "Error Message Type"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "stack": {
      "type": "string",
      "description": "Error Stack Trace"
    },
    "response": {
      "type": "object",
      "properties": {
        "statusCode": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "INCORRECT_INPUT_DATA"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "HTTP status code"
    },
    "message": {
      "type": "string",
      "description": "Error message for incorrect input data"
    }
  }
}

Reset Token Endpoint

Reset Token Endpoint
GET/api-users/users/reset-token/{refreshToken}

Some Text

This endpoint is used to reset the user’s token using a refresh token.

  • ticker: access.common - The subdomain to system services

Example URI

GET https://{ticker}.glprotocol.com/api-users/users/reset-token/{JWT_Bearer_Refresh_Token}
URI Parameters
HideShow
refreshToken
string (required) Example: {JWT_Bearer_Refresh_Token}

The refresh token

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "{User_ID}",
  "token": "{JWT_Bearer_Token}",
  "lang": "en",
  "refreshToken": "{JWT_Bearer_Refresh_Token}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The user's ID"
    },
    "token": {
      "type": "string",
      "description": "The new bearer token."
    },
    "lang": {
      "type": "string",
      "description": "The language preference of the user."
    },
    "refreshToken": {
      "type": "string",
      "description": "The new refresh token."
    }
  }
}
Response  200
HideShow

Invalid refresh token specified

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "message": "user.error:1C80006B:Provider routines::wrong final block length",
  "stack": "Error: error:1C80006B:Provider routines::wrong final block length\\n    at {STACK_TRACE}",
  "library": "Provider routines",
  "reason": "wrong final block length",
  "code": "ERR_OSSL_WRONG_FINAL_BLOCK_LENGTH"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "stack": {
      "type": "string"
    },
    "library": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    },
    "code": {
      "type": "string"
    }
  }
}
Response  400
HideShow

Refresh token is missing

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "INCORRECT_INPUT_DATA"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    }
  }
}

Entities

Display entities within the cryptocurrency ecosystem. It contains data points and details about exchanges, wallet providers, DeFi platforms, and other related entities. To view an entity, you need to know its ID. Therefore, you should first search for the ID by name, and then request information on the specific entity.

By Name

By Name
GET/api-labeling/entity?name={name}&$project[name]=1&$project[type]=1&$project[id]=1

Retrieve list of entities filtered by name

  • ticker: common - The subdomain to system services

Example URI

GET https://{ticker}.glprotocol.com/api-labeling/entity?name=.*bybit.*&%24project%5Bname%5D=1&%24project%5Btype%5D=1&%24project%5Bid%5D=1
URI Parameters
HideShow
name
string (required) Example: .*bybit.*

Regex filter for entity name

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "type": {
        "_id": "651d8a44e246cbd062b1f00e",
        "name": "Exchange",
        "score": 50
      },
      "id": "65ab88e58bc257cd15267c86",
      "name": "Bybit",
      "owner": "Bybit"
    },
    {
      "type": {
        "_id": "651d8a44e246cbd062b1f00e",
        "name": "Exchange",
        "score": 50
      },
      "id": "66f829885c9afc2c9a8760b3",
      "name": "Bybit Cold Wallet",
      "owner": "Bybit Cold Wallet"
    },
    {
      "type": {
        "_id": "652672e6b8ac18aaf5c52dc8",
        "name": "Cybercrime / Hack",
        "score": 100
      },
      "id": "67ba69e006c7efc512c20b9d",
      "name": "Bybit Hack Feb 2025",
      "owner": "Bybit Hack Feb 2025"
    }
  ],
  "count": 23
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "code": 401,
  "success": false,
  "path": "/api-labeling/entity?&$project[name]=1&$project[type]=1&$project[id]=1&name=.%2Abybit.%2A",
  "method": "GET",
  "timestamp": "4/6/2026, 10:55:21 PM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By ID

By ID
GET/api-labeling/entity?ids[]={id}

Retrieve list of entities filtered by id

  • ticker: common - The subdomain to system services

Example URI

GET https://{ticker}.glprotocol.com/api-labeling/entity?ids[]=65a8e2c98bc257cd15e58c41
URI Parameters
HideShow
id
string (required) Example: 65a8e2c98bc257cd15e58c41

entity ID

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "type": {
        "_id": "61766e49820e13d2b95ded4e",
        "name": "Low-risk exchange",
        "score": 30
      },
      "tags": [],
      "data": {
        "legalName": "",
        "isActive": true,
        "KYCStatus": "required",
        "isFiatCurrencyTrading": true,
        "isPrivacyCoinsSupported": true,
        "website": [
          "https://www.binance.com"
        ],
        "parentCompany": "",
        "domicileCountry": null,
        "status": "active",
        "description": "<p>Binance is the world's largest crypto exchange...</p>",
        "officeAddress": "",
        "screenshots": [
          {
            "name": "65a8e2c98bc257cd15e58c41_GL_screen_1769117493288.png",
            "image": "https://common.glprotocol.com/api-files/files/open/-65a8e2c98bc257cd15e58c41-GL-screen-1769117493288-5fb10795-f5f8-4e06-a797-c1112b564b2d.png"
          }
        ],
        "providedServices": [
          "67ae16d806c7efc5129a1d9e"
        ],
        "primaryOperationalRegions": [
          "AR",
          "UA",
          "IN",
          "TR"
        ],
        "restrictedJurisdictions": [
          "CA",
          "MY",
          "NL",
          "US"
        ],
        "languages": [
          "English",
          "Arabic"
        ],
        "socialNetworkLinks": [
          "https://twitter.com/binance"
        ],
        "regulatoryCompliance": [
          {
            "country": "FR",
            "localAuthority": "Autorité des Marchés Financiers (AMF)",
            "licenseNumber": "E2022-037",
            "licenseLink": "https://protectepargne.amf-france.org/acteurs-listes-blanches/psan/binance-france-sas",
            "registeredName": "BINANCE France SAS",
            "dates": {
              "from": 1651536000000
            },
            "status": null,
            "licenseType": "Crypto-Asset Service Provider",
            "address": "10 Avenue Franklin D. Roosevelt, 75008 Paris, France "
          }
        ],
        "banks": [],
        "paymentSystems": [],
        "contacts": [
          {
            "contactName": "Changpeng Zhao",
            "position": "Co-Founder & Former Chief Executive Officer (CEO)",
            "emailAddress": "",
            "contactLinks": [
              "https://www.linkedin.com/in/cpzhao/"
            ]
          }
        ],
        "contactsDepartments": [
          {
            "departmentName": "Customer Support",
            "departmentLinks": [
              "https://www.binance.com/en/support"
            ]
          }
        ],
        "countries": [
          "France",
          "Italy"
        ]
      },
      "alias": [
        {
          "value": "binance"
        }
      ],
      "logo": "https://common.glprotocol.com/api-files/files/open/250x250_Binance_20Pool.png",
      "updatedAt": "2026-03-31T06:11:45.817Z",
      "creatorId": "6446322993556887abd82feb",
      "id": "65a8e2c98bc257cd15e58c41",
      "name": "Binance",
      "owner": "Binance"
    }
  ],
  "count": 1
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "code": 401,
  "success": false,
  "path": "/api-labeling/entity?ids[]=65a8e2c98bc257cd15e58c41",
  "method": "GET",
  "timestamp": "4/6/2026, 10:55:10 PM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Get Transaction Risk Score

By Native Coin

By Native Coin
GET/api/report/tx_hash/{tx_hash}

Calculate and retrieve the risk score of a specific transaction by native coin (btc, eth, ltc, trx, bsv and etc.)

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/tx_hash/76a914db4d...88ac
URI Parameters
HideShow
tx_hash
string (required) Example: 76a914db4d...88ac

The transaction hash

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/tx_hash/0000",
  "method": "GET",
  "timestamp": "1/12/2026, 12:58:21 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By Token

By Token
GET/api/report/tx_hash/{tx_hash}?token={token}

Calculate and retrieve the risk score of a specific transaction by specific token of the smart contract.

  • ticker: eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/tx_hash/76a914db4d...88ac?token=0xdac17f958d2ee523a2206206994597c13d831ec7
URI Parameters
HideShow
tx_hash
string (required) Example: 76a914db4d...88ac

The transaction hash

token
string (optional) Example: 0xdac17f958d2ee523a2206206994597c13d831ec7

The blockchain token contract address. supported - unified search of all supported tokens, - search by native coin, {token_contract_address} - search by specific token.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855,
      "issuer": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "currency": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/tx_hash/0000?token=0xdac17f958d2ee523a2206206994597c13d831ec7",
  "method": "GET",
  "timestamp": "1/12/2026, 1:08:11 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By direction Source of Funds

By direction Source of Funds
GET/api/report/tx_hash/{tx_hash}?direction={direction}

Calculate and retrieve the risk score by Source of Funds of a specific transaction.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/tx_hash/76a914db4d...88ac?direction=0
URI Parameters
HideShow
tx_hash
string (required) Example: 76a914db4d...88ac

The transaction hash

direction
number (optional) Example: 0

The transaction search direction. 0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855,
      "issuer": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "currency": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/tx_hash/0000?direction=1",
  "method": "GET",
  "timestamp": "1/12/2026, 1:13:25 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Only Risk Score

Only Risk Score
GET/api/report/tx_hash/{tx_hash}?$project[totalFunds]={project_totalFunds}

Calculate and retrieve only the risk score of a specific transaction.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/tx_hash/76a914db4d...88ac?%24project%5BtotalFunds%5D=1
URI Parameters
HideShow
tx_hash
string (required) Example: 76a914db4d...88ac

The transaction hash

project_totalFunds
number (required) Example: 1

A query parameter used to pick totalFunds field (representing the risk score) from the response.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalFunds": 75
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/tx_hash/0000?$project[totalFunds]=1",
  "method": "GET",
  "timestamp": "1/12/2026, 1:14:44 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Parameter $project[totalFunds]= must be equal to one of the allowed values 0|1. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "statusCode": 400,
    "message": "must be equal to one of the allowed values",
    "schema": [
      "[0",
      "1]"
    ]
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "statusCode": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "schema": {
          "type": "array"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

With Enabled Alerts

With Enabled Alerts
GET/api/report/tx_hash/{tx_hash}?alertEnable=true

Calculate and retrieve the risk score of a specific transaction with enabled alerts (btc, eth, ltc, trx, bsv and etc.)

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/tx_hash/76a914db4d...88ac?alertEnable=true
URI Parameters
HideShow
tx_hash
string (required) Example: 76a914db4d...88ac

The transaction hash

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855
    }
  ],
  "alerts": [
    {
      "address": "``",
      "userId": "65bc4bc3a2...fa614dbd3a",
      "read": false,
      "archive": false,
      "amount": 14021.175131,
      "triggeredAmount": 7027.097484,
      "depth": 1,
      "priority": 50,
      "score": 72,
      "fiat": "USD",
      "weight": 0.401347,
      "labels": [
        "ransomware"
      ],
      "updatedAt": "1970-01-19T14:33:38.923Z",
      "alertId": "6913bbc3d3cce32b43ddae35",
      "coin": "btc",
      "directTx": "e71839ca539f6f86...eeb8e332a7e3dc4d3c371d1d04",
      "data": [
        {
          "share": 1,
          "directStamp": 1607618923,
          "amountCur": 7027.097484,
          "depth": 1,
          "label": "Ransomware",
          "entity": "66f83b9e5c9afc2c9a87a988",
          "owner": "File-Locker",
          "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
          "tx_hash": "e71839ca539f6f8652e36...eb8e332a7e3dc4d3c371d1d04"
        }
      ],
      "results": [
        true
      ],
      "title": "name",
      "logical": "$anyOf",
      "riskReport": true,
      "addressesCount": [],
      "addresses": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    },
    "alerts": {
      "type": "array"
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/tx_hash/0000?alertEnable=true",
  "method": "GET",
  "timestamp": "1/12/2026, 1:15:33 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Get Address Risk Score

By Native Coin

By Native Coin
GET/api/report/address/{address}

Calculate and retrieve the risk score of a blockchain address based on historical transactions by native coin (btc, eth, ltc, trx, bsv and etc.)

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/address/1BoatSLRHtKNngkdXEeobR76b53LETtpyT
URI Parameters
HideShow
address
string (required) Example: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT

The blockchain address

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "totalFunds": 31,
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/address/bc1qy7gxhxkkdw800000g8j4fnr3qz6v28d36y6xpt",
  "method": "GET",
  "timestamp": "1/12/2026, 1:18:53 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "totalFunds": {
      "type": "number"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By Tokens

By Tokens
GET/api/report/address/{address}?token={token}

Calculate and retrieve the risk score of a blockchain address by specific token of the smart contract based on historical transactions.

  • ticker: eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/address/0xca258d51a825c82d16ce54dc61b8abc95021d17b?token=0xdac17f958d2ee523a2206206994597c13d831ec7
URI Parameters
HideShow
address
string (required) Example: 0xca258d51a825c82d16ce54dc61b8abc95021d17b

The blockchain address

token
string (optional) Example: 0xdac17f958d2ee523a2206206994597c13d831ec7

The blockchain token contract address. supported - unified search of all supported tokens, - search by native coin, {token_contract_address} - search by specific token.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855,
      "issuer": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "currency": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Contract Address is Not Allowed For Risk Report. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "statusCode": 400,
    "message": "CONTRACTS_NOT_ALLOWED_FOR_RISK_REPORT",
    "error": "Bad Request"
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "Risk Report for contracts is not supported. Please enter an externally-owned account address."
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "statusCode": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "totalFunds": 31,
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/address/0xca000001a825c82d16ce54dc61b8abc95021d17b?token=0xdac17f958d2ee523a2206206994597c13d831ec7",
  "method": "GET",
  "timestamp": "1/12/2026, 1:20:45 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "totalFunds": {
      "type": "number"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By direction Use of Funds

By direction Use of Funds
GET/api/report/address/{address}?direction={direction}

Calculate and retrieve the risk score only by Use of funds of a blockchain address based on historical transactions.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/address/1BoatSLRHtKNngkdXEeobR76b53LETtpyT?direction=2
URI Parameters
HideShow
address
string (required) Example: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT

The blockchain address

direction
number (optional) Example: 2

The transaction search direction. 0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "totalFunds": 31,
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/address/0xca000001a825c82d16ce54dc61b8abc95021d17b?direction=1",
  "method": "GET",
  "timestamp": "1/12/2026, 1:24:02 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "totalFunds": {
      "type": "number"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Only Risk Score

Only Risk Score
GET/api/report/address/{address}?$project[totalFunds]={project_totalFunds}

Calculate and retrieve only the risk score of a blockchain address based on historical transactions.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/address/0xca258d51a825c82d16ce54dc61b8abc95021d17b?%24project%5BtotalFunds%5D=1
URI Parameters
HideShow
address
string (required) Example: 0xca258d51a825c82d16ce54dc61b8abc95021d17b

The blockchain address

project_totalFunds
number (required) Example: 1

A query parameter used to pick totalFunds field (representing the risk score) from the response.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalFunds": 75
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Contract Address is Not Allowed For Risk Report. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "statusCode": 400,
    "message": "CONTRACTS_NOT_ALLOWED_FOR_RISK_REPORT",
    "error": "Bad Request"
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "Risk Report for contracts is not supported. Please enter an externally-owned account address."
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "statusCode": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "totalFunds": 31,
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/address/0xca000001a825c82d16ce54dc61b8abc95021d17b?$project[totalFunds]=1",
  "method": "GET",
  "timestamp": "1/12/2026, 1:24:50 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "totalFunds": {
      "type": "number"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Parameter $project[totalFunds]= must be equal to one of the allowed values 0|1. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "statusCode": 400,
    "message": "must be equal to one of the allowed values",
    "schema": [
      "[0",
      "1]"
    ]
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "statusCode": {
          "type": "number"
        },
        "message": {
          "type": "string"
        },
        "schema": {
          "type": "array"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

With Enabled Alerts

With Enabled Alerts
GET/api/report/address/{address}?alertEnable=true

Calculate and retrieve the risk score of a blockchain address based on historical transactions with enabled alerts (btc, eth, ltc, trx, bsv and etc.)

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/report/address/1BoatSLRHtKNngkdXEeobR76b53LETtpyT?alertEnable=true
URI Parameters
HideShow
address
string (required) Example: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT

The blockchain address

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 251000000000000000,
  "progress": 100,
  "depth": 3,
  "directTxCount": 10,
  "totalFunds": 75,
  "sources": [
    {
      "directTx": "0xbd54a...750bbec0407dc7dc04",
      "tx_hash": "0x0fd34...dc61b8abc95021d17b",
      "address": "0xca258d51a825c82d16ce54dc61b8abc95021d17b",
      "depth": 3,
      "funds": {
        "name": "{TAG_NAME}",
        "score": 50,
        "default": true
      },
      "amount": 31643005583457000,
      "share": 10,
      "owner": "OWNER_NAME",
      "listType": "Known sources",
      "directStamp": 1697553611,
      "timestamp": 1697525855
    }
  ],
  "alerts": [
    {
      "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
      "userId": "65bc4bc3a297dcfa614dbd3a",
      "read": false,
      "archive": false,
      "amount": 15.483272,
      "triggeredAmount": 15.483272,
      "depth": 1,
      "priority": 50,
      "score": 30,
      "fiat": "USD",
      "weight": 0.12002,
      "labels": [
        "low-risk exchange"
      ],
      "updatedAt": "1970-01-20T13:38:25.571Z",
      "alertId": "6913bbc3d3cce32b43ddae35",
      "coin": "btc",
      "directTx": "70eb3736c0bde98877f480a652b22b5dca8494c8b2fb95f8af62bf5d7f28f8fd",
      "data": [
        {
          "share": 1,
          "directStamp": 1690705571,
          "amountCur": 15.483272,
          "depth": 1,
          "label": "Low-risk exchange",
          "owner": "Coinbase",
          "address": "3EoNsoh8FcpFTywJ1DZiYFUJjqQM4ffopp",
          "tx_hash": "70eb3736c0bde98877f480a652b22b5dca8494c8b2fb95f8af62bf5d7f28f8fd"
        }
      ],
      "results": [
        true
      ],
      "title": "name",
      "logical": "$anyOf",
      "riskReport": true,
      "addressesCount": [],
      "addresses": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number",
      "description": "Amount of incoming transaction funds for calculation"
    },
    "progress": {
      "type": "number",
      "description": "Internal additional field"
    },
    "depth": {
      "type": "number",
      "description": "Maximum value of the depth of the found source"
    },
    "directTxCount": {
      "type": "number",
      "description": "Direct transaction count"
    },
    "totalFunds": {
      "type": "number",
      "description": "Calculated RISK SCORE value using the user’s selected formula (default or sensitive)"
    },
    "sources": {
      "type": "array",
      "description": "Array with found sources"
    },
    "alerts": {
      "type": "array",
      "description": "Array with found alerts. If alerts are enabled, the response will contain this array."
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Found. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "totalFunds": 31,
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/api/report/address/0xca000001a825c82d16ce54dc61b8abc95021d17b?alertEnable=true",
  "method": "GET",
  "timestamp": "1/12/2026, 1:26:21 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "totalFunds": {
      "type": "number"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Get Address Balance

By Native Coin

By Native Coin
GET/api/explorer/getBalance/{address}

Get the native coin balance of a specific blockchain address.

  • ticker: eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/explorer/getBalance/TRBqACCXaLTYsKxWzDwbfyN1shtWs479TC
URI Parameters
HideShow
address
string (required) Example: TRBqACCXaLTYsKxWzDwbfyN1shtWs479TC

The blockchain address

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "address": "{REQUESTED_ADDRESS}",
  "contract": "``",
  "balance": {
    "amount": 376.71644,
    "symbol": "TRX",
    "price": 41.024859,
    "priceTimestamp": 1713517606492
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "contract": {
      "type": "string"
    },
    "balance": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number"
        },
        "symbol": {
          "type": "string",
          "enum": [
            "TRX",
            "ETH"
          ]
        },
        "price": {
          "type": "number"
        },
        "priceTimestamp": {
          "type": "number"
        }
      }
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By Token

By Token
GET/api/explorer/getBalance/{address}?contract={contract}

Get the token balance of a specific blockchain address.

  • ticker: eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/api/explorer/getBalance/TRBqACCXaLTYsKxWzDwbfyN1shtWs479TC?contract=contract
URI Parameters
HideShow
address
string (required) Example: TRBqACCXaLTYsKxWzDwbfyN1shtWs479TC

The blockchain address

contract
string (required) Example: contract

The blockchain token contract address

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "address": "{REQUESTED_ADDRESS}",
  "contract": "{TOKEN_CONTRACT_ADDRESS}",
  "balance": {
    "amount": 12634.43649,
    "symbol": "{TOKEN_SYMBOL}",
    "price": 12641.726313,
    "priceTimestamp": 1713517535003
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "contract": {
      "type": "string"
    },
    "balance": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number"
        },
        "symbol": {
          "type": "string"
        },
        "price": {
          "type": "number"
        },
        "priceTimestamp": {
          "type": "number"
        }
      }
    }
  }
}
Response  400
HideShow

Address is Not Valid. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "errors": [
      {
        "instancePath": "/address",
        "schemaPath": "#/properties/address/$ts",
        "keyword": "required",
        "params": {},
        "message": "must pass \\\"$ts\\\" keyword validation",
        "schema": "AddressId",
        "data": "SomeInvalidAddress"
      }
    ],
    "status": 400
  },
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.Http Exception"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array"
        },
        "status": {
          "type": "number"
        }
      }
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "success": false,
  "data": {
    "messageType": "error",
    "message": "user.User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Essential Support

Get information about essential blockchains

By Transaction

By Transaction
GET/essential-api-{essential_blockchain_ticker}/report/tx_hash/{tx_hash}?direction={direction}&token={token_contract_address}

Retrieve detailed information about a specific transaction for essential blockchains

  • ticker: common - subdomain for this request always common

  • essential_blockchain_ticker: polygon|glmr|arb|base|dot|sol|ton|xrp|worldcoin|optimism|xlm|tempo|cardano - The essential blockchain ticker

Example URI

GET https://{ticker}.glprotocol.com/essential-api-{essential_blockchain_ticker}/report/tx_hash/0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f
URI Parameters
HideShow
essential_blockchain_ticker
string (required) Example: {essential_blockchain_ticker}

The essential blockchain to query

tx_hash
string (required) Example: 0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1

The transaction hash

direction
string (required) Example: 2

0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

token_contract_address
string (required) Example: 0xc2132d05d31c914a87c6611c10748aeb04b58e8f

The essential blockchain token contract address. - (blank value) search by native coin, {token_contract_address} - search by specific token.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 18394532,
  "progress": 100,
  "depth": 2,
  "directTxCount": 2,
  "totalFunds": 50.95,
  "totalFundsDefault": 50,
  "totalFundsSensitive": 50,
  "totalFundsSeries": 50.95,
  "sources": [
    {
      "directTx": "\"0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1\"",
      "directionUp": false,
      "funds": {
        "name": "\"DEX\"",
        "score": 50
      },
      "owner": "\"Uniswap\"",
      "depth": 2,
      "amount": 9197266,
      "currency": "\"0xc2132d05d31c914a87c6611c10748aeb04b58e8f\"",
      "tx_hash": "\"0x755a883e328cfb7d9994c1940e2547f8de71a0e8971ed55fabeee6bc57bab331\"",
      "address": "\"0x9b08288c3be4f62bbf8d1c20ac9c5e6f9467d8b7\"",
      "timestamp": 1685019783,
      "listType": "\"Known sources\"",
      "share": 1
    },
    {
      "directTx": "\"0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1\"",
      "directionUp": true,
      "funds": {
        "name": "\"exchange\"",
        "score": 50
      },
      "owner": "\"OKX\"",
      "depth": 2,
      "amount": 9197266,
      "currency": "\"0xc2132d05d31c914a87c6611c10748aeb04b58e8f\"",
      "tx_hash": "\"0x7fa32534b3372cb9656ef5bb897e67520c561f57a76b45baf87489a729674d94\"",
      "address": "\"0x06959153b974d0d5fdfd87d561db6d8d4fa0bb0b\"",
      "timestamp": 1691726959,
      "listType": "\"Known sources\"",
      "share": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number"
    },
    "progress": {
      "type": "number"
    },
    "depth": {
      "type": "number"
    },
    "directTxCount": {
      "type": "number"
    },
    "totalFunds": {
      "type": "number"
    },
    "totalFundsDefault": {
      "type": "number"
    },
    "totalFundsSensitive": {
      "type": "number"
    },
    "totalFundsSeries": {
      "type": "number"
    },
    "sources": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Transaction Not Found

Headers
Content-Type: application/json
Body
{
  "messageType": "\"Error\"",
  "status": 404,
  "code": 404,
  "success": false,
  "path": "\"/essential-api-polygon/report/tx_hash/0xda852cac14840170ae6655c3f0071209c09f98c1aafb450945c5be5a1?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f\"",
  "method": "\"GET\"",
  "timestamp": "\"3/4/2025, 1:16:58 PM\"",
  "data": {
    "messageType": "\"error\"",
    "message": "\"ENOENT\""
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Transaction Hash Not Specified. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "message": "Cannot GET /essential-api-polygon/report/tx_hash/?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "error": "Not Found",
    "statusCode": 404
  },
  "status": 404,
  "options": {},
  "message": "Cannot GET /essential-api-polygon/report/tx_hash/?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "name": "NotFoundException",
  "code": 404,
  "success": false,
  "path": "/essential-api-polygon/report/tx_hash/?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "method": "GET",
  "timestamp": "1/12/2026, 1:35:47 PM",
  "data": {
    "messageType": "error",
    "message": "Cannot GET /essential-api-polygon/report/tx_hash/?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        },
        "statusCode": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "options": {
      "type": "object",
      "properties": {}
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "status": 401,
  "message": "User not found",
  "name": "HttpException",
  "code": 401,
  "success": false,
  "path": "/essential",
  "method": "GET",
  "timestamp": "3/4/2025, 10:03:51 AM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string",
      "description": "api-glmr/report/tx_hash/0x69033d0891348c8ac8e9456c8226ddc91099f97fc4ad0e888c736b2dd3bb5fec?direction=0&token=&tokenTicker=GLMR (string)"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

By Address

By Address
GET/essential-api-{essential_blockchain_ticker}/report/address/{address}?direction={direction}&token={token_contract_address}

Retrieve detailed information about a last transaction for provided address for essential blockchains

  • ticker: common - subdomain for this request always common

  • essential_blockchain_ticker: polygon|glmr|arb|base|dot|sol|ton|xrp|worldcoin|optimism|xlm|tempo|cardano - The essential blockchain ticker

Example URI

GET https://{ticker}.glprotocol.com/essential-api-{essential_blockchain_ticker}/report/address/0x85b4Ce35C2e36aC6405455A3D3Ae947972864f66?direction=2&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f
URI Parameters
HideShow
essential_blockchain_ticker
string (required) Example: {essential_blockchain_ticker}

The essential blockchain to query

address
string (required) Example: 0x85b4Ce35C2e36aC6405455A3D3Ae947972864f66

The address

direction
string (required) Example: 2

0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

token_contract_address
string (required) Example: 0xc2132d05d31c914a87c6611c10748aeb04b58e8f

The essential blockchain token contract address. - (blank value) search by native coin, {token_contract_address} - search by specific token.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalAmount": 18394532,
  "progress": 100,
  "depth": 2,
  "directTxCount": 2,
  "totalFunds": 50.95,
  "totalFundsDefault": 50,
  "totalFundsSensitive": 50,
  "totalFundsSeries": 50.95,
  "sources": [
    {
      "directTx": "\"0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1\"",
      "directionUp": false,
      "funds": {
        "name": "\"DEX\"",
        "score": 50
      },
      "owner": "\"Uniswap\"",
      "depth": 2,
      "amount": 9197266,
      "currency": "\"0xc2132d05d31c914a87c6611c10748aeb04b58e8f\"",
      "tx_hash": "\"0x755a883e328cfb7d9994c1940e2547f8de71a0e8971ed55fabeee6bc57bab331\"",
      "address": "\"0x9b08288c3be4f62bbf8d1c20ac9c5e6f9467d8b7\"",
      "directStamp": 1740770954,
      "timestamp": 1685019783,
      "listType": "\"Known sources\"",
      "share": 1
    },
    {
      "directTx": "\"0xda852cac14840170ae6655c3f00712bfe67fd09c09f98c1aafb450945c5be5a1\"",
      "directionUp": true,
      "funds": {
        "name": "\"exchange\"",
        "score": 50
      },
      "owner": "\"OKX\"",
      "depth": 2,
      "amount": 9197266,
      "currency": "\"0xc2132d05d31c914a87c6611c10748aeb04b58e8f\"",
      "tx_hash": "\"0x7fa32534b3372cb9656ef5bb897e67520c561f57a76b45baf87489a729674d94\"",
      "address": "\"0x06959153b974d0d5fdfd87d561db6d8d4fa0bb0b\"",
      "directStamp": 1740770954,
      "timestamp": 1691726959,
      "listType": "\"Known sources\"",
      "share": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "totalAmount": {
      "type": "number"
    },
    "progress": {
      "type": "number"
    },
    "depth": {
      "type": "number"
    },
    "directTxCount": {
      "type": "number"
    },
    "totalFunds": {
      "type": "number"
    },
    "totalFundsDefault": {
      "type": "number"
    },
    "totalFundsSensitive": {
      "type": "number"
    },
    "totalFundsSeries": {
      "type": "number"
    },
    "sources": {
      "type": "array"
    }
  }
}
Response  404
HideShow

Address Not Found

Headers
Content-Type: application/json
Body
{
  "messageType": "Error",
  "meta": {
    "spamAmount": 0,
    "spamCount": 0,
    "cashbackCount": 0,
    "totalFunds": 31
  },
  "status": 404,
  "code": 404,
  "success": false,
  "path": "/essential-api-polygon/report/address/0x85b4Ce35C2e36aC6405455A3D3Ae947972864f66?direction=1&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "method": "GET",
  "timestamp": "1/12/2026, 2:24:43 PM",
  "data": {
    "messageType": "error",
    "message": "ENOENT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "messageType": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "spamAmount": {
          "type": "number"
        },
        "spamCount": {
          "type": "number"
        },
        "cashbackCount": {
          "type": "number"
        },
        "totalFunds": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Specified. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "message": "Cannot GET /essential-api-polygon/report/address?direction=1&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "error": "Not Found",
    "statusCode": 404
  },
  "status": 404,
  "options": {},
  "message": "Cannot GET /essential-api-polygon/report/address?direction=1&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "name": "NotFoundException",
  "code": 404,
  "success": false,
  "path": "/essential-api-polygon/report/address?direction=1&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "method": "GET",
  "timestamp": "1/12/2026, 2:27:14 PM",
  "data": {
    "messageType": "error",
    "message": "Cannot GET /essential-api-polygon/report/address?direction=1&token=0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        },
        "statusCode": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "options": {
      "type": "object",
      "properties": {}
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "status": 401,
  "message": "User not found",
  "name": "HttpException",
  "code": 401,
  "success": false,
  "path": "/essential",
  "method": "GET",
  "timestamp": "3/4/2025, 10:03:51 AM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string",
      "description": "api-arb/report/address/0x85b4Ce35C2e36aC6405455A3D3Ae947972864f66123?shallow=false&direction=2&token=&tokenTicker=ETH (string)"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Get Address Tokens

Get Address Tokens
GET/essential-api-{essential_blockchain_ticker}/explorer/getAddressTokens/{address}?supported={supported}&$limit={limit}

Retrieve token contracts for a specific address on essential blockchains. The response returns a data array of tokens. For each token, use data[i].address as token_contract_address in By Transaction and By Address requests. For the native coin, address is an empty string. When supported is omitted, the observed behavior matches supported=false.

  • ticker: common - subdomain for this request always common

  • essential_blockchain_ticker: polygon|glmr|arb|base|dot|sol|ton|xrp|worldcoin|optimism|xlm|tempo|cardano - The essential blockchain ticker

Example URI

GET https://{ticker}.glprotocol.com/essential-api-{essential_blockchain_ticker}/explorer/getAddressTokens/0xF3604FA7edF245f344acd0f4083E409BB2fEfd98?supported=true&%24limit=1000
URI Parameters
HideShow
essential_blockchain_ticker
string (required) Example: {essential_blockchain_ticker}

The essential blockchain to query

address
string (required) Example: 0xF3604FA7edF245f344acd0f4083E409BB2fEfd98

The address

supported
boolean (optional) Example: true

true returns only supported tokens, false or omitted returns all detected tokens for the address

limit
number (optional) Example: 1000

Query parameter accepted by the endpoint. In observed responses for this address, the returned item count did not change when $limit was reduced

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "data": [
    {
      "name": "ETH",
      "symbol": "ETH",
      "decimals": 18,
      "icon": "",
      "address": ""
    },
    {
      "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "icon": ""
    },
    {
      "address": "0x25118290e6a5f4139381d072181157035864099d",
      "name": "RAIN",
      "symbol": "RAIN",
      "decimals": 18,
      "icon": ""
    },
    {
      "address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
      "name": "USD₮0",
      "symbol": "USD₮0",
      "decimals": 6,
      "icon": ""
    },
    {
      "address": "0x1cd9a56c8c2ea913c70319a44da75e99255aa46f",
      "name": "Orbiter Token",
      "symbol": "OBT",
      "decimals": 18,
      "icon": ""
    },
    {
      "address": "0x912ce59144191c1204e64559fe8253a0e49e6548",
      "name": "Arbitrum",
      "symbol": "ARB",
      "decimals": 18,
      "icon": ""
    },
    {
      "address": "0x5979d7b546e38e414f7e9822514be443a4800529",
      "name": "Wrapped liquid staked Ether 2.0",
      "symbol": "wstETH",
      "decimals": 18,
      "icon": ""
    }
  ]
}
Response  400
HideShow

Address is Not Valid. Example from live request.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "instancePath": "/address",
      "schemaPath": "#/properties/address/$ts",
      "keyword": "$ts",
      "params": {},
      "message": "must pass \"$ts\" keyword validation",
      "schema": "AddressId",
      "data": "not-an-address"
    }
  ],
  "status": 400,
  "code": 400,
  "success": false,
  "path": "/essential",
  "method": "GET",
  "timestamp": "4/6/2026, 10:42:30 PM",
  "data": {
    "messageType": "error",
    "message": "400 payload/address must pass \"$ts\" keyword validation"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string",
      "description": "api-arb/explorer/getAddressTokens/not-an-address?supported=true&%24limit=5 (string)"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

Address Not Specified. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": {
    "message": "Cannot GET /essential-api-arb/explorer/getAddressTokens/?supported=true&%24limit=5",
    "error": "Not Found",
    "statusCode": 404
  },
  "status": 404,
  "options": {},
  "message": "Cannot GET /essential-api-arb/explorer/getAddressTokens/?supported=true&%24limit=5",
  "name": "NotFoundException",
  "code": 404,
  "success": false,
  "path": "/essential",
  "method": "GET",
  "timestamp": "4/6/2026, 10:42:59 PM",
  "data": {
    "messageType": "error",
    "message": "Cannot GET /essential-api-arb/explorer/getAddressTokens/?supported=true&%24limit=5"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "error": {
          "type": "string"
        },
        "statusCode": {
          "type": "number"
        }
      }
    },
    "status": {
      "type": "number"
    },
    "options": {
      "type": "object",
      "properties": {}
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string",
      "description": "api-arb/explorer/getAddressTokens/?supported=true&%24limit=5 (string)"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request. Example with Wrapper.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "status": 401,
  "message": "User not found",
  "name": "HttpException",
  "code": 401,
  "success": false,
  "path": "/essential",
  "method": "GET",
  "timestamp": "4/6/2026, 10:39:25 PM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string",
      "description": "api-arb/explorer/getAddressTokens/0xF3604FA7edF245f344acd0f4083E409BB2fEfd98?supported=true&%24limit=5 (string)"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Monitoring

Monitor advanced-chain addresses.

Add Address To Monitoring

Add Address To Monitoring
POST/api/monitoring/addressToMonitor

Add a single address to monitoring.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The advanced blockchain to query (as a subdomain)

Example URI

POST https://{ticker}.glprotocol.com/api/monitoring/addressToMonitor
Request
HideShow
Headers
x-api-key: {Api_key}
Body
{
  "address": "18VWHjMt4ixHddPPbs6righWTs3Sg2QNcn",
  "checkLastTen": false,
  "blockchain": "BTC"
}
Schema
{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "The blockchain address to add to monitoring."
    },
    "checkLastTen": {
      "type": "boolean",
      "description": "Controls whether the initial monitoring calculation should be limited to the latest ten direct transactions."
    },
    "blockchain": {
      "enum": [
        "BTC",
        "LTC",
        "BSV",
        "ETH",
        "TRX",
        "BNB",
        "AVAX"
      ],
      "description": "Blockchain code matching the selected advanced network."
    }
  },
  "required": [
    "address",
    "blockchain"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  201
HideShow

Successfully added to monitoring.

Headers
Content-Type: application/json
Body
{
  "success": true,
  "data": {
    "added": 1,
    "notFound": 0,
    "duplicate": 0
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Indicates that the request was processed successfully."
    },
    "data": {
      "type": "object",
      "properties": {
        "added": {
          "type": "number",
          "description": "Number of addresses added to monitoring."
        },
        "notFound": {
          "type": "number",
          "description": "Number of addresses that were not found during processing."
        },
        "duplicate": {
          "type": "number",
          "description": "Number of addresses already present in monitoring."
        }
      }
    }
  }
}
Response  201
HideShow

Address is already present in monitoring. The endpoint may still return HTTP 201 with an error payload.

Headers
Content-Type: application/json
Body
{
  "success": false,
  "data": {
    "messageType": "BadRequestException",
    "message": "Address already added to monitor",
    "stack": "BadRequestException: ADDRESS_ALREADY_ADDED_TO_MONITOR",
    "response": {
      "statusCode": 400,
      "message": "ADDRESS_ALREADY_ADDED_TO_MONITOR",
      "error": "Bad Request"
    },
    "status": 400,
    "name": "BadRequestException"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "stack": {
          "type": "string"
        },
        "response": {
          "type": "object",
          "properties": {
            "statusCode": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "error": {
              "type": "string"
            }
          }
        },
        "status": {
          "type": "number"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}
Response  400
HideShow

Bad Request - address is invalid or the request body is malformed.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "instancePath": "/address",
      "schemaPath": "#/properties/address/$ts",
      "keyword": "$ts",
      "params": {},
      "message": "must pass \\\"$ts\\\" keyword validation",
      "schema": "AddressId",
      "data": "SomeInvalidAddress"
    },
    {
      "instancePath": "/address",
      "schemaPath": "#/properties/address/pattern",
      "keyword": "pattern",
      "params": {
        "pattern": "^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$"
      },
      "message": "must match pattern \\\"^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$\\\"",
      "schema": "^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$",
      "data": "SomeInvalidAddress"
    }
  ],
  "status": 400,
  "code": 400,
  "success": false,
  "path": "/api/monitoring/addressToMonitor",
  "method": "POST",
  "timestamp": "4/17/2026, 10:11:22 AM",
  "data": {
    "messageType": "error",
    "message": "400 payload/address must pass \\\"$ts\\\" keyword validation, payload/address must match pattern \\\"^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$\\\""
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "status": 401,
  "message": "User not found",
  "name": "HttpException",
  "code": 401,
  "success": false,
  "path": "/api/monitoring/addressToMonitor",
  "method": "POST",
  "timestamp": "4/17/2026, 10:11:07 AM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Remove Address From Monitoring

Remove Address From Monitoring
DELETE/api/monitoring/addressToMonitor/{address}

Remove a single address from monitoring.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The advanced blockchain to query (as a subdomain)

Example URI

DELETE https://{ticker}.glprotocol.com/api/monitoring/addressToMonitor/18VWHjMt4ixHddPPbs6righWTs3Sg2QNcn
URI Parameters
HideShow
address
string (required) Example: 18VWHjMt4ixHddPPbs6righWTs3Sg2QNcn

The blockchain address to remove from monitoring.

Request
HideShow
Headers
x-api-key: {Api_key}
Response  200
HideShow

Successfully removed from monitoring.

Headers
Content-Type: application/json
Body
{
  "success": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Indicates that the request was processed successfully."
    }
  }
}
Response  400
HideShow

Bad Request - address is invalid.

Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "instancePath": "/address",
      "schemaPath": "#/properties/address/$ts",
      "keyword": "$ts",
      "params": {},
      "message": "must pass \\\"$ts\\\" keyword validation",
      "schema": "AddressId",
      "data": "SomeInvalidAddress"
    },
    {
      "instancePath": "/address",
      "schemaPath": "#/properties/address/pattern",
      "keyword": "pattern",
      "params": {
        "pattern": "^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$"
      },
      "message": "must match pattern \\\"^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$\\\"",
      "schema": "^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$",
      "data": "SomeInvalidAddress"
    }
  ],
  "status": 400,
  "code": 400,
  "success": false,
  "path": "/api/monitoring/addressToMonitor/SomeInvalidAddress",
  "method": "DELETE",
  "timestamp": "4/17/2026, 12:35:59 PM",
  "data": {
    "messageType": "error",
    "message": "400 payload/address must pass \\\"$ts\\\" keyword validation, payload/address must match pattern \\\"^(1|3)[a-km-zA-HJ-NP-Z1-9]{25,34}$|^bc1[a-zA-Z0-9]{6,}$\\\""
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "type": "array"
    },
    "status": {
      "type": "number"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  401
HideShow

Unauthorized Request.

Headers
Content-Type: application/json
Body
{
  "response": "User not found",
  "status": 401,
  "message": "User not found",
  "name": "HttpException",
  "code": 401,
  "success": false,
  "path": "/api/monitoring/addressToMonitor/18VWHjMt4ixHddPPbs6righWTs3Sg2QNcn",
  "method": "DELETE",
  "timestamp": "4/17/2026, 12:35:58 PM",
  "data": {
    "messageType": "error",
    "message": "User not found"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "response": {
      "type": "string"
    },
    "status": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "number"
    },
    "success": {
      "type": "boolean"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "messageType": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Webhooks

Receive Global Ledger events — address score updates and alerts — on your own HTTPS endpoint.

Webhook delivery uses two building blocks:

  • A webhook endpoint is a callback destination: a URL plus an enabled state, identified by a webhookId you choose.

  • A webhook binding selects which events are delivered to that destination. A binding is an event route: a type, an optional subType, and an optional coin.

One endpoint may have any number of bindings. Create the endpoint once, then attach one binding per event route you want to receive. Bindings are persistent by default; a one-shot binding (isOneShot: true) is removed after its first successful delivery and is meant only for temporary callbacks.

Quick start:

  1. Create a webhook endpoint (PUT /integration/webhooks/{webhookId}).

  2. Attach a binding for the event route you need (POST /integration/webhooks/{webhookId}/bindings).

  3. For monitoring.score, make sure the address is monitored for your account — creating a binding does not add addresses to monitoring. For alert, configure the alert in your Global Ledger account.

  4. Receive and verify callbacks on your URL (see Receiving Callbacks).

Event Routes

type subType coin Delivered when
monitoring.score none (must be omitted) optional The score of a monitored address is updated
alert monitoring optional A configured alert produces a new alert event
alert risk-report optional A configured risk-report alert produces a new alert event
alert behavior-alert optional A behavior alert produces a new alert event

Only the values above are accepted. monitoring.score takes no subType. Omit subType or coin when not needed — never send null, "null", or an empty string. On a blockchain-specific subdomain, an explicit coin must match that blockchain.

A standalone client walkthrough is available here: v1 Webhooks — Client Integration Guide.

Authorization

Authenticate every webhook operation with your API key passed as the Authorization header value, without a Bearer prefix. This is the recommended authorization method for all webhook operations, and every example in this section uses it.

X-Signature Calculation

POST and PUT requests must additionally carry an X-Signature header; GET and DELETE requests need only Authorization. The signature (hmac variable) is calculated from the API key, the API secret, and the exact JSON request body:

var input = { API_KEY } + "." + JSON.stringify( JSON.parse( request.data ) );

var HMAC = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(input,{ API_SECRET }));

Receiving Callbacks

Every delivery is an HTTPS POST to the endpoint URL with these headers:

Authorization: {API_KEY}
X-SIGNATURE: {HMAC}
X-GL-WEBHOOK-ID: {WEBHOOK_ID}
X-GL-WEBHOOK-TYPE: monitoring.score
X-GL-WEBHOOK-COIN: btc

X-GL-WEBHOOK-SUBTYPE is present when the event route has a subtype; X-GL-WEBHOOK-COIN is present when the event has a coin. Use these route headers to dispatch events.

To verify a callback, recompute the HMAC with the X-Signature Calculation formula — input {API_KEY}. plus the compact JSON body exactly as delivered — and compare it with the X-SIGNATURE header.

A monitoring.score callback body is an array of score updates:

[
    {
        "address": "{ADDRESS}",
        "score": 42.7,
        "timestamp": "2026-07-21T12:34:56.000Z",
        "coin": "btc"
    }
]

An alert callback body contains the new alert events:

{
    "subjects": [
        {
            "subjectId": "664f73107e88eb9ebaafb5d4",
            "alertId": "664f73107e88eb9ebaafb5d5",
            "title": "High risk exposure",
            "priority": 2,
            "address": "{ADDRESS}",
            "directTx": ""
        }
    ]
}

Additional fields may be present in either body.

The three operations at the end of this section (Create Subscription, Add to Monitoring, Remove from Monitoring) predate webhook bindings. They are deprecated and planned for removal in a future release and remain only for existing integrations.

Create/Update Webhook

Create/Update Webhook
PUT/integration/webhooks/{webhookId}

Creates or updates a webhook endpoint. The endpoint owns the callback URL and enabled state; event routing is configured through webhook bindings.

The legacy events field is stored and returned for compatibility only — it is ignored for routing, so omit it and configure routing with bindings instead.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

PUT https://{ticker}.glprotocol.com/integration/webhooks/w123
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
X-Signature: {HMAC}
Body
{
  "enabled": true,
  "url": "{CALLBACK_URL}"
}
Response  200
HideShow

Successfully Updated

Body
``
Response  201
HideShow

Successfully Created

Headers
Content-Type: application/json
Body
{
  "id": "{WEBHOOK_ID}",
  "enabled": true,
  "events": [],
  "url": "{CALLBACK_URL}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the webhook"
    },
    "enabled": {
      "type": "boolean",
      "description": "A flag indicating if the webhook endpoint can receive callbacks"
    },
    "events": {
      "description": "Legacy metadata retained for compatibility; ignored for event routing"
    },
    "url": {
      "type": "string",
      "description": "The URL where callbacks are delivered"
    }
  },
  "required": [
    "id",
    "enabled",
    "url"
  ]
}
Response  304
HideShow

Not Modified

Response  401
HideShow

Unauthorized Request - Authorization or/and X-Signature are not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

Get a single Webhook

Get a single Webhook
GET/integration/webhooks/{webhookId}

Get a single webhook endpoint with the provided ID

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/integration/webhooks/w123
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

The endpoint response represents a webhook object.

Headers
Content-Type: application/json
Body
{
  "id": "{WEBHOOK_ID}",
  "enabled": true,
  "events": [],
  "url": "{CALLBACK_URL}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the webhook. Replace `{WEBHOOK_ID}` with the actual webhook ID."
    },
    "enabled": {
      "type": "boolean",
      "description": "Indicates whether the webhook endpoint can receive callbacks."
    },
    "events": {
      "description": "Legacy metadata retained for compatibility; ignored for event routing."
    },
    "url": {
      "type": "string",
      "description": "The URL to which callbacks are delivered."
    }
  },
  "required": [
    "id",
    "enabled",
    "url"
  ]
}
Response  401
HideShow

Unauthorized Request - Authorization is not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  404
HideShow

Webhook Not Found

Headers
Content-Type: application/json
Body
{
  "statusCode": 404,
  "message": "Webhook absent",
  "code": "HttpException",
  "timestamp": "5/9/2024, 9:09:27 AM",
  "path": "{URL_PATH}",
  "method": "GET"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    }
  }
}

Get all Webhooks

Get all Webhooks
GET/integration/webhooks/

Get all the webhook endpoints created by user

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/integration/webhooks/
Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

The endpoint response represents a list of webhook objects.

Headers
Content-Type: application/json
Body
[
  {
    "id": "{WEBHOOK_ID_1}",
    "enabled": true,
    "events": [],
    "url": "{CALLBACK_URL}"
  },
  {
    "id": "{WEBHOOK_ID_2}",
    "enabled": true,
    "events": [],
    "url": "{CALLBACK_URL}"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  401
HideShow

Unauthorized Request - Authorization is not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

Delete a single Webhook

Delete a single Webhook
DELETE/integration/webhooks/{webhookId}

Delete a single webhook endpoint with the provided ID. Deleting an endpoint also removes its bindings.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

DELETE https://{ticker}.glprotocol.com/integration/webhooks/w123
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

Successfully Deleted

Body
``
Response  404
HideShow

When a webhook with the given ID is not found, the following error is returned

Headers
Content-Type: application/json
Body
{
  "statusCode": 404,
  "message": "Webhook absent",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

Create Webhook Binding

Create Webhook Binding
POST/integration/webhooks/{webhookId}/bindings

Attaches an event route to an existing webhook endpoint. The binding, not the webhook endpoint, owns type, subType, coin, and isOneShot.

Bindings are persistent by default. Set isOneShot: true only when a single temporary delivery is required — a one-shot binding is consumed after its first successful delivery.

For alert routes, add one supported subType, for example {"type": "alert", "subType": "risk-report", "coin": "btc"}.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

POST https://{ticker}.glprotocol.com/integration/webhooks/w123/bindings
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
X-Signature: {HMAC}
Body
{
  "type": "monitoring.score",
  "coin": "btc"
}
Response  201
HideShow

Webhook binding created

Headers
Content-Type: application/json
Body
{
  "id": "{BINDING_ID}",
  "webhookId": "{WEBHOOK_ID}",
  "type": "monitoring.score",
  "coin": "btc",
  "isOneShot": false,
  "createdAt": "2026-07-21T12:00:00.000Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the created binding. Use it to delete the binding later."
    },
    "webhookId": {
      "type": "string",
      "description": "The ID of the webhook endpoint the binding is attached to."
    },
    "type": {
      "type": "string",
      "description": "The event type routed by this binding."
    },
    "coin": {
      "type": "string",
      "description": "The blockchain scope of the route. Omitted when the binding is not coin-scoped."
    },
    "isOneShot": {
      "type": "boolean",
      "description": "Whether the binding is removed after its first successful delivery."
    },
    "createdAt": {
      "type": "string",
      "description": "The date and time when the binding was created."
    }
  },
  "required": [
    "id",
    "webhookId",
    "type",
    "isOneShot",
    "createdAt"
  ]
}
Response  401
HideShow

Unauthorized Request - Authorization or/and X-Signature are not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  404
HideShow

Webhook Not Found

Headers
Content-Type: application/json
Body
{
  "statusCode": 404,
  "message": "Webhook absent",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "POST"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    }
  }
}
Response  412
HideShow

Precondition Failed - the event route is not registered (unknown type or subType), subType is sent with monitoring.score, an optional field is sent as a null-like value, or coin does not match the blockchain subdomain.

Headers
Content-Type: application/json
Body
{
  "statusCode": 412,
  "message": "{ERROR_MESSAGE}",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

List Webhook Bindings

List Webhook Bindings
GET/integration/webhooks/{webhookId}/bindings{?type,subType,coin,isOneShot}

Lists event bindings attached to one webhook endpoint. Omitted subType and coin filters mean the default route dimension; do not send null-like values.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/integration/webhooks/w123/bindings?type=monitoring.score&subType=risk-report&coin=btc&isOneShot=false
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

type
string (optional) Example: monitoring.score

Filter by event type (monitoring.score or alert)

subType
string (optional) Example: risk-report

Filter by event subtype (monitoring, risk-report, or behavior-alert)

coin
string (optional) Example: btc

Filter by blockchain scope

isOneShot
string (optional) Example: false

Filter by one-shot flag (true or false)

Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

Webhook bindings list

Headers
Content-Type: application/json
Body
[
  {
    "id": "{BINDING_ID}",
    "webhookId": "{WEBHOOK_ID}",
    "type": "monitoring.score",
    "coin": "btc",
    "isOneShot": false,
    "createdAt": "2026-07-21T12:00:00.000Z"
  }
]
Response  401
HideShow

Unauthorized Request - Authorization is not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  404
HideShow

Webhook Not Found

Headers
Content-Type: application/json
Body
{
  "statusCode": 404,
  "message": "Webhook absent",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "GET"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    }
  }
}

List all Webhook Bindings

List all Webhook Bindings
GET/integration/webhook-bindings{?type,subType,coin,isOneShot}

Lists bindings across all webhook endpoints of the current user. Accepts the same filters as the per-endpoint list.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

GET https://{ticker}.glprotocol.com/integration/webhook-bindings?type=alert&subType=risk-report&coin=btc&isOneShot=false
URI Parameters
HideShow
type
string (optional) Example: alert

Filter by event type (monitoring.score or alert)

subType
string (optional) Example: risk-report

Filter by event subtype (monitoring, risk-report, or behavior-alert)

coin
string (optional) Example: btc

Filter by blockchain scope

isOneShot
string (optional) Example: false

Filter by one-shot flag (true or false)

Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

Webhook bindings list

Headers
Content-Type: application/json
Body
[
  {
    "id": "{BINDING_ID}",
    "webhookId": "{WEBHOOK_ID}",
    "type": "alert",
    "subType": "risk-report",
    "coin": "btc",
    "isOneShot": false,
    "createdAt": "2026-07-21T12:00:00.000Z"
  }
]
Response  401
HideShow

Unauthorized Request - Authorization is not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

Delete Webhook Binding

Delete Webhook Binding
DELETE/integration/webhooks/{webhookId}/bindings/{bindingId}

Deletes one binding by its ID — the recommended way to remove an event route.

For bulk cleanup there are also selector-based deletions: POST /integration/webhooks/{webhookId}/bindings/delete-by-selector (one endpoint) and POST /integration/webhook-bindings/delete-by-selector (all endpoints of the current user). Both are signed POST requests taking {"type", "subType", "coin"} selectors that match exactly by default — an omitted subType or coin matches only bindings without that field; deleting across those dimensions requires explicit includeSubTypes/includeCoins flags plus confirm: true. They respond with {"deletedCount": <number>}. Prefer deletion by binding ID unless you really need bulk cleanup.

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

DELETE https://{ticker}.glprotocol.com/integration/webhooks/w123/bindings/{BINDING_ID}
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

bindingId
string (required) Example: {BINDING_ID}

The ID of the binding to delete

Request
HideShow
Headers
Authorization: {API_KEY}
Response  200
HideShow

Successfully Deleted

Body
``
Response  401
HideShow

Unauthorized Request - Authorization is not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  404
HideShow

Webhook Not Found

Headers
Content-Type: application/json
Body
{
  "statusCode": 404,
  "message": "Webhook absent",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "DELETE"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    }
  }
}

Create Subscription - Deprecated

Create Subscription - Deprecated
POST/integration/score/address

Deprecated and planned for removal in a future release. Prefer a persistent monitoring.score binding plus the monitoring lifecycle; use a one-shot binding when a temporary score callback is required.

Create subscription for addresses to be monitored

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

  • idempotency-key: super_secret_word - Some unique value for each request

  • webhook-id: 123 - The Webhook ID

Example URI

POST https://{ticker}.glprotocol.com/integration/score/address
Request
HideShow

Note: If subscribe is true, it keeps monitoring and webhook receives updates when addresses score changes, otherwise it receives addresses score only once.

Headers
Authorization: {API_KEY}
X-Signature: {HMAC}
idempotency-key: {UNIQUE_REQUEST_ID}
webhook-id: {WEBHOOK_ID}
Body
{
    "addresses": [
     "{ADDRESS}",
     "{ADDRESS}"
    ],
    "subscribe": true || false // set true to receive updated score after each new address transaction
}
Response  202
HideShow

Subscription Successfully Created

Headers
Content-Type: text/html
Body
Data received
Response  202
HideShow

Success Response when a request is done with the same idempotency-key

Headers
Content-Type: application/json
Body
{
  "statusCode": 202,
  "message": "DATA_RECEIVED",
  "code": "HttpException",
  "timestamp": "2024-05-09T10:29:14.812Z",
  "path": "URL_PATH",
  "method": "POST"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "message": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "method": {
      "type": "string"
    }
  }
}
Response  401
HideShow

Unauthorized Request - Authorization or/and X-Signature are not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  412
HideShow

Precondition Failed - addresses in the request body are not set or invalid, idempotency-key or webhook-id are not set in the request Headers or webhook-id does not exist.

Headers
Content-Type: application/json
Body
{
  "statusCode": 412,
  "message": "{ERROR_MESSAGE}",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  500
HideShow

Error when a blockchain address has no transactions and subscribe is either not specified or set to false in the request body.

Body
``

Add to Monitoring - Deprecated

Add to Monitoring - Deprecated
PUT/integration/webhooks/{webhookId}/subscription/score/address

Deprecated and planned for removal in a future release. Prefer a persistent monitoring.score binding plus the monitoring lifecycle for score delivery.

Add a list of addresses to monitoring

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

PUT https://{ticker}.glprotocol.com/integration/webhooks/w123/subscription/score/address
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
X-Signature: {HMAC}
Body
{
  "op": "add",
  "addresses": [
    "{ADDRESS}",
    "{ADDRESS}"
  ]
}
Response  200
HideShow

Successfully added to monitoring

Headers
Content-Type: text/plain
Body
Data received
Response  401
HideShow

Unauthorized Request - Authorization or/and X-Signature are not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  412
HideShow

Precondition Failed - addresses in the request body are not set or invalid, webhookId does not exist.

Headers
Content-Type: application/json
Body
{
  "statusCode": 412,
  "message": "{ERROR_MESSAGE}",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

Remove from Monitoring - Deprecated

Remove from Monitoring - Deprecated
PUT/integration/webhooks/{webhookId}/subscription/score/address

Deprecated and planned for removal in a future release. Removal stays paired with the deprecated add operation; new integrations should manage score delivery through bindings and the monitoring lifecycle.

Remove a list of addresses from monitoring

  • ticker: btc|ltc|bsv|eth|tron|bnb|avax - The blockchain to query (as a subdomain)

Example URI

PUT https://{ticker}.glprotocol.com/integration/webhooks/w123/subscription/score/address
URI Parameters
HideShow
webhookId
string (required) Example: w123

The ID of the webhook

Request
HideShow
Headers
Authorization: {API_KEY}
X-Signature: {HMAC}
Body
{
  "op": "remove",
  "addresses": [
    "{ADDRESS}",
    "{ADDRESS}"
  ]
}
Response  200
HideShow

Successfully removed from monitoring

Headers
Content-Type: text/plain
Body
Data received
Response  401
HideShow

Unauthorized Request - Authorization or/and X-Signature are not set or invalid in the request Headers

Headers
Content-Type: application/json
Body
{
  "statusCode": 401,
  "message": "Unauthorized",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:33:42.734Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}
Response  412
HideShow

Precondition Failed - addresses in the request body are not set or invalid, webhookId does not exist.

Headers
Content-Type: application/json
Body
{
  "statusCode": 412,
  "message": "{ERROR_MESSAGE}",
  "code": "HttpException",
  "timestamp": "2024-05-02T15:39:42.084Z",
  "path": "{REQUEST_URL}",
  "method": "{REQUEST_METHOD}"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "The HTTP status code of the response."
    },
    "message": {
      "type": "string",
      "description": "The message explaining the status."
    },
    "code": {
      "type": "string",
      "description": "The exceptional case that has occurred."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time when the exception happened."
    },
    "path": {
      "type": "string",
      "description": "The URL path that has been attempted to access."
    },
    "method": {
      "type": "string",
      "description": "The HTTP method (like GET, POST, PUT, DELETE) used for the request."
    }
  },
  "required": [
    "statusCode",
    "message",
    "code",
    "timestamp",
    "path",
    "method"
  ]
}

PDF reports

{userId} - obtained from authentication step from the top of the document

Get unified address pdf report （Advanced Support Only）

Get unified address pdf report （Advanced Support Only）
GET/report/address/{address}?currencyKey={currencyKey}&userId={userId}&tokenAddress={tokenAddress}&preferredCurrency={preferredCurrency}&timezone={timezone}&activePartBarValue={activePartBarValue}&direction={direction}

Get PDF report for address for all supported tokens

  • ticker: pdfgen.common - The ticker is always pdfgen.common. It is a subdomain within which it is deployed pdf report support

  • address: 0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9 - existing address

  • userId: 628dfd99581d3845bbd52988 - id of the user

  • currencyKey: btc|eth|ltc|trx|bsv|bnb|avax - blockchain/network

  • tokenAddress: all|0x41e5560054824ea6b0732e656e3ad64e20e94e45|'' - ‘all’ - unified report for all supported tokens, ‘0x41e5560054824ea6b0732e656e3ad64e20e94e45’ - supported token address, ‘’ - leave blank for native coin token

  • preferredCurrency: USD|EUR - currency

  • timezone: Europe/Kiev - timezone

  • activePartBarValue: type|owner - group by

  • direction: 0|1|2 - 0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

Example URI

GET https://{ticker}.glprotocol.com/report/address/0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9?currencyKey=eth&userId=628dfd99581d3845bbd52988&tokenAddress=all&preferredCurrency=USD&timezone=Europe/Kiev&activePartBarValue=type&direction=2
URI Parameters
HideShow
address
string (required) Example: 0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9
userId
string (required) Example: 628dfd99581d3845bbd52988
currencyKey
string (required) Example: eth
tokenAddress
string (required) Example: all
preferredCurrency
string (required) Example: USD
timezone
string (required) Example: Europe/Kiev
activePartBarValue
string (required) Example: type
direction
string (required) Example: 2
Request
HideShow
Headers
x-api-key: Api_key
Response  200
HideShow
Body
report_{address}.pdf
Response  400
HideShow

Response for request with invalid address

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`
Response  400
HideShow

Response for unauthorized request

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`

Get token address pdf report （Advanced Support Only）

Get token address pdf report （Advanced Support Only）
GET/report/address/{address}?currencyKey={currencyKey}&userId={userId}&tokenAddress={tokenAddress}&preferredCurrency={preferredCurrency}&timezone={timezone}&activePartBarValue={activePartBarValue}&direction={direction}

Get PDF report for address for selected token

  • ticker: pdfgen.common - The ticker is always pdfgen.common. It is a subdomain within which it is deployed pdf report support

  • address: 0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9 - existing address

  • userId: 628dfd99581d3845bbd52988 - id of the user

  • currencyKey: btc|eth|ltc|trx|bsv|bnb|avax - blockchain/network

  • tokenAddress: all|0x41e5560054824ea6b0732e656e3ad64e20e94e45|'' - ‘all’ - unified report for all supported tokens, ‘0x41e5560054824ea6b0732e656e3ad64e20e94e45’ - supported token address, ‘’ - leave blank for native coin token

  • preferredCurrency: USD|EUR - currency

  • timezone: Europe/Kiev - timezone

  • activePartBarValue: type - blockchain/network

  • direction: 0|1|2 - 0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

Example URI

GET https://{ticker}.glprotocol.com/report/address/0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9?currencyKey=eth&userId=628dfd99581d3845bbd52988&tokenAddress=0x41e5560054824ea6b0732e656e3ad64e20e94e45&preferredCurrency=USD&timezone=Europe/Kiev&activePartBarValue=type&direction=2
URI Parameters
HideShow
address
string (required) Example: 0x8bd0b65a50ef5cef84fec420be7b89ed1470ceb9
userId
string (required) Example: 628dfd99581d3845bbd52988
currencyKey
string (required) Example: eth
tokenAddress
string (required) Example: 0x41e5560054824ea6b0732e656e3ad64e20e94e45
preferredCurrency
string (required) Example: USD
timezone
string (required) Example: Europe/Kiev
activePartBarValue
string (required) Example: type
direction
string (required) Example: 2
Request
HideShow
Headers
x-api-key: Api_key
Response  200
HideShow
Body
report_{address}.pdf
Response  400
HideShow

Response for request with invalid address

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`
Response  400
HideShow

Response for unauthorized request

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`

Get token transaction pdf report （Advanced Support Only）

Get token transaction pdf report （Advanced Support Only）
GET/report/tx/{txHash}?currencyKey={currencyKey}&userId={userId}&tokenAddress={tokenAddress}&preferredCurrency={preferredCurrency}&timezone={timezone}&activePartBarValue={activePartBarValue}&direction={direction}

Get PDF report for transaction for selected token

  • ticker: pdfgen.common - The ticker is always pdfgen.common. It is a subdomain within which it is deployed pdf report support

  • txHash: 0x64dec2f706b17d86dbe59bf1a829f06d4c40f5d5bc5bae62f68b851049c3e58c - existing transaction

  • userId: 628dfd99581d3845bbd52988 - id of the user

  • currencyKey: btc|eth|ltc|trx|bsv|bnb|avax - blockchain/network

  • tokenAddress: all|0x41e5560054824ea6b0732e656e3ad64e20e94e45|'' - ‘all’ - unified report for all supported tokens, ‘0x41e5560054824ea6b0732e656e3ad64e20e94e45’ - supported token address, ‘’ - leave blank for native coin token

  • preferredCurrency: USD|EUR - currency

  • timezone: Europe/Kiev - timezone

  • activePartBarValue: type - blockchain/network

  • direction: 0|1|2 - 0 - is the Source of Funds, 1 - is the Use of Funds, 2 - common, Source of Funds + Use of Funds (default value if not specified).

Example URI

GET https://{ticker}.glprotocol.com/report/tx/0x64dec2f706b17d86dbe59bf1a829f06d4c40f5d5bc5bae62f68b851049c3e58c?currencyKey=eth&userId=628dfd99581d3845bbd52988&tokenAddress=0xa0b73e1ff0b80914ab6fe0444e65848c4c34450b&preferredCurrency=USD&timezone=Europe/Kiev&activePartBarValue=type&direction=2
URI Parameters
HideShow
txHash
string (required) Example: 0x64dec2f706b17d86dbe59bf1a829f06d4c40f5d5bc5bae62f68b851049c3e58c
userId
string (required) Example: 628dfd99581d3845bbd52988
currencyKey
string (required) Example: eth
tokenAddress
string (required) Example: 0xa0b73e1ff0b80914ab6fe0444e65848c4c34450b
preferredCurrency
string (required) Example: USD
timezone
string (required) Example: Europe/Kiev
activePartBarValue
string (required) Example: type
direction
string (required) Example: 2
Request
HideShow
Headers
x-api-key: Api_key
Response  200
HideShow
Body
report_{trancaction}.pdf
Response  400
HideShow

Response for request with invalid address

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`
Response  400
HideShow

Response for unauthorized request

Body
`400 Bad request
An error occurred while generating the PDF  document. Please try again`

FAQ

Frequently Asked Questions about the Global Ledger API. Below are common questions with concise answers to assist developers.

How can I download the YAML file?

You can download the .yaml files, which contains useful configurations for the API, by clicking the link below (it will open in a new tab):

Download advanced yaml
Download essential yaml

Why are there separate API requests for retrieving risk scores in Essential and Advanced support chains?

This is due to implementation-specific differences in the current version of the API. These discrepancies will be resolved in APIv2, where we plan to standardize risk score retrieval across both Essential and Advanced blockchain support tiers.

Should different endpoints be used when checking risk scores for transactions versus addresses?

Yes. Risk score checks are performed via distinct endpoints:

  • /api/report/tx_hash/ for transaction-level checks

  • /api/report/address for address-level checks

To evaluate specific tokens or all supported assets within a transaction or address report, use the token= query parameter. This parameter accepts either:

  • A smart contract address of the token (You may also specify any custom token by its contract address, including newly created tokens.)

  • The keyword "supported" to include all top-ranked assets (based on CoinMarketCap’s top 1000+ list)

When using the token query parameter, can I pass a ticker symbol like “USDT” instead of a contract address?

No. The token parameter only accepts:

  • A smart contract address

  • The keyword "supported"

Ticker symbols (e.g., "USDT") are not supported due to the possibility of multiple tokens sharing identical names or symbols across different blockchains.

Can I receive webhook notifications when the risk score of a transfer changes?

Webhook functionality is designed to monitor address-level changes, not individual transactions. When an address is registered for webhook monitoring, any updates to its risk score will trigger a callback in the following format:

{
  "_id": "68e4c595d173aac4c6a28e1c",
  "path": "testwebhook",
  "data": [
    {
      "address": "TJJxTXzJ7o9S89WcdwhsjpVUX1ozEWKHtc",
      "timestamp": 1759823252800,
      "score": 51
    }
  ]
}

Triggers include:

  • New incoming transactions

  • New outgoing transactions

  • Changes in risk attribution from sources or labels

Webhook events currently support only address-level monitoring (score.address.deep, score.address.standard). Transaction-level webhook support is not available.

Is there a customer-facing API guide for Counterparty Report and Entity Report that can be shared with prospects?

Yes, we provide a 5-step integration guide for both Counterparty and Entity Reports. Please note that the current flow is somewhat complex, but simplification is underway as part of the APIv2 roadmap.

Can I determine whether an address belongs to a specific VASP or CASP using the API?

Yes. If a label is available for the address, it can be retrieved via the Get Info by Address endpoint. This includes VASP/CASP attribution where applicable.

If a customer uses only the API (without GUI access) and accidentally triggers a large volume of wallet checks due to a bug, is there a way to prevent or mitigate this?

Currently, we do not offer built-in rate limiting or daily quota enforcement. If such an incident occurs, we recommend contacting our support team. We will investigate the issue collaboratively and, if appropriate, restore the account balance to its pre-incident state.

When querying GET “Address Risk Score”, I see 100 sources returned. Is pagination supported for this endpoint?

No. The endpoint returns a fixed set of the most recent 100 entries in each direction:

  • 100 for Source of Funds

  • 100 for Use of Funds

Pagination or offset parameters are not currently supported.

Is there an endpoint that allows batch retrieval of label or risk data for multiple addresses?

At this time, risk and label data can only be retrieved one address at a time. Batch queries are not yet supported.

Generated by aglio on 24 Jul 2026