Forta API GraphQL API Reference
Free GraphQL API access to alerts and blockchain projects data
Terms of Service
API Endpoints
https://api.forta.network/graphql
Forta API Support
The API is in beta mode. If you see any bugs or issues, please let us know at github:forta-network/forta-api or discord.
Queries
alerts
Description
Fetches alerts
Response
Returns an AlertsResponse
Arguments
Name | Description |
---|---|
input - AlertsInput
|
Example
Query
query alerts($input: AlertsInput) {
alerts(input: $input) {
alerts {
...AlertFragment
}
pageInfo {
...AlertPageInfoFragment
}
}
}
Variables
{"input": AlertsInput}
Response
{
"data": {
"alerts": {
"alerts": [Alert],
"pageInfo": AlertPageInfo
}
}
}
batch
Description
Fetches a batch given its batch ID
Example
Query
query batch($id: String!) {
batch(id: $id) {
id
parentId
createdAt
chainId
scanNodeId
receiptId
}
}
Variables
{"id": "xyz789"}
Response
{
"data": {
"batch": {
"id": "abc123",
"parentId": "xyz789",
"createdAt": "xyz789",
"chainId": 123,
"scanNodeId": "xyz789",
"receiptId": "abc123"
}
}
}
batches
Description
Fetches batches
Response
Returns a BatchesResponse
Arguments
Name | Description |
---|---|
input - BatchesInput
|
Example
Query
query batches($input: BatchesInput) {
batches(input: $input) {
batches {
...BatchFragment
}
pageInfo {
...BatchPageInfoFragment
}
}
}
Variables
{"input": BatchesInput}
Response
{
"data": {
"batches": {
"batches": [Batch],
"pageInfo": BatchPageInfo
}
}
}
bots
Description
Fetches bots
Response
Returns a BotsResponse
Arguments
Name | Description |
---|---|
input - BotsInput
|
Example
Query
query bots($input: BotsInput) {
bots(input: $input) {
bots {
...BotFragment
}
pageInfo {
...BotPageInfoFragment
}
}
}
Variables
{"input": BotsInput}
Response
{
"data": {
"bots": {
"bots": [Bot],
"pageInfo": BotPageInfo
}
}
}
labels
Description
Fetches labels
Response
Returns a LabelsResponse
Arguments
Name | Description |
---|---|
input - LabelsInput
|
Example
Query
query labels($input: LabelsInput) {
labels(input: $input) {
labels {
...LabelEventFragment
}
pageInfo {
...LabelPageInfoFragment
}
}
}
Variables
{"input": LabelsInput}
Response
{
"data": {
"labels": {
"labels": [LabelEvent],
"pageInfo": LabelPageInfo
}
}
}
project
Description
Fetches a web3 project given its project ID
Example
Query
query project($id: String!) {
project(id: $id) {
contacts {
...ContactsFragment
}
name
id
social {
...SocialFragment
}
token {
...TokenFragment
}
website
}
}
Variables
{"id": "xyz789"}
Response
{
"data": {
"project": {
"contacts": Contacts,
"name": "abc123",
"id": "xyz789",
"social": Social,
"token": Token,
"website": "abc123"
}
}
}
projects
Description
Fetches all existing web3 projects recorded in github repo: https://github.com/ethereum-lists/contracts/tree/main/projects
Response
Returns a ProjectsResponse
Arguments
Name | Description |
---|---|
input - ProjectsInput
|
Example
Query
query projects($input: ProjectsInput) {
projects(input: $input) {
edges {
...ProjectEdgeFragment
}
pageInfo {
...ProjectPageInfoFragment
}
}
}
Variables
{"input": ProjectsInput}
Response
{
"data": {
"projects": {
"edges": [ProjectEdge],
"pageInfo": ProjectPageInfo
}
}
}
Types
Alert
Description
Alert information
Fields
Field Name | Description |
---|---|
alertId - String
|
Unique string to identify this class of finding, primarily used to group similar findings for the end user |
addresses - [String]
|
List of addresses involved in the alert |
contracts - [Contract]
|
List of contracts related to the alert |
createdAt - String
|
Timestamp when the alert was published |
description - String
|
Text description of the alert |
hash - String
|
Alert hash identifier |
metadata - JSONObject
|
Extra alert information |
name - String
|
Alert name |
projects - [Project]
|
List of Web3 projects related to the alert |
protocol - String
|
Name of protocol being reported on |
scanNodeCount - Int
|
Number of scanners that found the alert |
severity - String
|
Impact level of finding CRITICAL - Exploitable vulnerabilities, massive impact on users/funds HIGH - Exploitable under more specific conditions, significant impact on users/funds MEDIUM - Notable unexpected behaviours, moderate to low impact on users/funds LOW - Minor oversights, negligible impact on users/funds INFO - Miscellaneous behaviours worth describing |
source - AlertSource
|
Source where the alert was detected |
findingType - String
|
Type of finding UNKNOWN_TYPE EXPLOIT SUSPICIOUS DEGRADED INFO |
alertDocumentType - String
|
Type of alert UNKNOWN PRIVATE BLOCK TRANSACTION COMBINATION |
relatedAlerts - [String]
|
List of alerts involved in the alert |
chainId - NonNegativeInt
|
Chain id |
labels - [Label]
|
List of labels related to the alert |
addressBloomFilter - BloomFilter
|
Bloom filter for addresses |
truncated - Boolean
|
Flags alert as truncated for size purposes |
Example
{
"alertId": "abc123",
"addresses": ["abc123"],
"contracts": [Contract],
"createdAt": "abc123",
"description": "abc123",
"hash": "abc123",
"metadata": {},
"name": "xyz789",
"projects": [Project],
"protocol": "xyz789",
"scanNodeCount": 987,
"severity": "xyz789",
"source": AlertSource,
"findingType": "xyz789",
"alertDocumentType": "abc123",
"relatedAlerts": ["abc123"],
"chainId": 123,
"labels": [Label],
"addressBloomFilter": BloomFilter,
"truncated": true
}
AlertEndCursor
Fields
Field Name | Description |
---|---|
blockNumber - NonNegativeInt!
|
|
alertId - String!
|
Example
{"blockNumber": 123, "alertId": "xyz789"}
AlertEndCursorInput
Description
Search after specified block number and alertId
Fields
Input Field | Description |
---|---|
blockNumber - NonNegativeInt!
|
|
alertId - String!
|
Example
{"blockNumber": 123, "alertId": "xyz789"}
AlertPageInfo
Fields
Field Name | Description |
---|---|
endCursor - AlertEndCursor!
|
|
hasNextPage - Boolean!
|
|
totalAlerts - TotalMetadata!
|
Example
{
"endCursor": AlertEndCursor,
"hasNextPage": true,
"totalAlerts": TotalMetadata
}
AlertSource
Description
Source where the threat was detected
Fields
Field Name | Description |
---|---|
transactionHash - String
|
Transaction where the threat was detected |
bot - Bot
|
Bot that triggered the alert |
block - Block
|
Block where the threat was detected |
sourceAlert - SourceAlertEvent
|
Source alert event the threat was detected |
Example
{
"transactionHash": "abc123",
"bot": Bot,
"block": Block,
"sourceAlert": SourceAlertEvent
}
AlertsInput
Description
Alert list input
Fields
Input Field | Description |
---|---|
addresses - [String]
|
Indicate a list of addresses. Alerts returned will have those addresses involved. |
after - AlertEndCursorInput
|
Search results after the specified cursor |
alertId - String
|
Filter alerts by alert-id. |
alertIds - [String]
|
Filter alerts by multiple alert-ids. |
alertHash - String
|
Get a specific alert by alert hash. |
alertName - String
|
Filter alerts by alert name. |
blockDateRange - DateRange
|
Block Date range Alerts returned will be between the specified start and end block timestamp dates when the threats were detected. By default, start and end date will be set to local query execution date. |
blockNumberRange - BlockRange
|
Block number range Alerts for the block number range will be returned. |
blockTimestampRange - TimestampRange
|
Block Timestamp range Alerts returned will be between the specified start and end block timestamp when the threats were detected. |
blockSortDirection - Sort
|
Indicate sorting order by block number, 'desc' or 'asc'. Default is 'desc'. |
bots - [String]
|
Indicate a list of bot hashes. Alerts returned will only be from any of those bots. |
chainId - NonNegativeInt
|
Indicate a chain Id: EIP155 identifier of the chain Alerts returned will only be from the specific chain Id Default is 1 = Ethereum Mainnet. |
createdSince - NonNegativeInt
|
Indicate number of milliseconds Alerts returned will be alerts created since the number of milliseconds indicated ago. |
createdBefore - NonNegativeInt
|
Indicate number of milliseconds Alerts returned will be alerts created before the number of milliseconds indicated ago. |
first - NonNegativeInt
|
Indicate max number of results. |
projectId - String
|
Indicate a project Id. Alerts returned will only be from that project. |
scanNodeConfirmations - scanNodeFilters
|
Filter alerts by number of scan nodes confirming the alert. |
severities - [String]
|
Filter alerts by severity levels. |
transactionHash - String
|
Indicate a transaction hash Alerts returned will only be from that transaction. |
labelMetadata - String
|
Filter alerts by label metadata |
afterCreatedAtDate - String
|
Filter alerts by created at date after the specified date in RFC 3399 format. |
beforeCreatedAtDate - String
|
Filter alerts by created at date before the specified date in RFC 3399 format. |
Example
{
"addresses": ["abc123"],
"after": AlertEndCursorInput,
"alertId": "xyz789",
"alertIds": ["abc123"],
"alertHash": "xyz789",
"alertName": "xyz789",
"blockDateRange": DateRange,
"blockNumberRange": BlockRange,
"blockTimestampRange": TimestampRange,
"blockSortDirection": "asc",
"bots": ["abc123"],
"chainId": 123,
"createdSince": 123,
"createdBefore": 123,
"first": 123,
"projectId": "xyz789",
"scanNodeConfirmations": scanNodeFilters,
"severities": ["xyz789"],
"transactionHash": "xyz789",
"labelMetadata": "abc123",
"afterCreatedAtDate": "xyz789",
"beforeCreatedAtDate": "abc123"
}
AlertsResponse
Fields
Field Name | Description |
---|---|
alerts - [Alert]
|
|
pageInfo - AlertPageInfo
|
Example
{
"alerts": [Alert],
"pageInfo": AlertPageInfo
}
Batch
Description
Batch information
Fields
Field Name | Description |
---|---|
id - String
|
Batch id |
parentId - String
|
Id of preceding batch to form chain |
createdAt - String
|
Timestamp when the batch was published |
chainId - NonNegativeInt
|
chain id on batch was created from |
scanNodeId - String
|
Reference to scanner that sent this batch request |
receiptId - String
|
Receipt id for the batch |
Example
{
"id": "abc123",
"parentId": "xyz789",
"createdAt": "abc123",
"chainId": 123,
"scanNodeId": "xyz789",
"receiptId": "xyz789"
}
BatchEndCursor
Fields
Field Name | Description |
---|---|
createdAt - String
|
Example
{"createdAt": "xyz789"}
BatchEndCursorInput
Description
Search after specified batch after id
Fields
Input Field | Description |
---|---|
createdAt - DateTime
|
Example
{"createdAt": "2007-12-03T10:15:30Z"}
BatchPageInfo
Fields
Field Name | Description |
---|---|
endCursor - BatchEndCursor
|
|
hasNextPage - Boolean
|
|
totalBatches - TotalMetadata!
|
Example
{
"endCursor": BatchEndCursor,
"hasNextPage": true,
"totalBatches": TotalMetadata
}
BatchesInput
Description
Batch list input
Fields
Input Field | Description |
---|---|
after - BatchEndCursorInput
|
Search results after the specified cursor |
parentId - String
|
Filter batch by parent's Id. |
scanNodeId - String
|
Filter batches by scanner. |
receiptId - String
|
Filter batches by receiptId. |
chainId - NonNegativeInt
|
Indicate a chain Id: EIP155 identifier of the chain Alerts returned will only be from the specific chain Id Default is 1 = Ethereum Mainnet. |
first - NonNegativeInt
|
Indicate max number of results. |
createdRange - TimestampRange
|
Batches returned will only be those created in the time range |
Example
{
"after": BatchEndCursorInput,
"parentId": "xyz789",
"scanNodeId": "abc123",
"receiptId": "xyz789",
"chainId": 123,
"first": 123,
"createdRange": TimestampRange
}
BatchesResponse
Fields
Field Name | Description |
---|---|
batches - [Batch]
|
|
pageInfo - BatchPageInfo
|
Example
{
"batches": [Batch],
"pageInfo": BatchPageInfo
}
Block
Description
Block information
Fields
Field Name | Description |
---|---|
number - NonNegativeInt
|
Block number |
hash - String
|
Block hash |
timestamp - String
|
Block's timestamp |
chainId - NonNegativeInt
|
Block's chain id |
Example
{
"number": 123,
"hash": "abc123",
"timestamp": "abc123",
"chainId": 123
}
BlockRange
Description
Block range
Fields
Input Field | Description |
---|---|
startBlockNumber - NonNegativeInt!
|
|
endBlockNumber - NonNegativeInt!
|
Example
{"startBlockNumber": 123, "endBlockNumber": 123}
BloomFilter
Description
Bloom filter information
Fields
Field Name | Description |
---|---|
k - String
|
Number of hash functions used in filter |
m - String
|
Capacity of bloom filter |
bitset - String
|
Bloom filter as bitset, encoded in base64 |
itemCount - NonNegativeInt
|
Total number of addresses in filter |
Example
{
"k": "xyz789",
"m": "abc123",
"bitset": "abc123",
"itemCount": 123
}
Boolean
Description
The Boolean
scalar type represents true
or false
.
Bot
Description
Bot information
Fields
Field Name | Description |
---|---|
chainIds - [String]
|
|
createdAt - String
|
|
description - String
|
|
developer - String
|
Bot Developer address |
docReference - String
|
Bot Documentation IPFS reference |
enabled - Boolean
|
|
id - String
|
Bot id |
image - String
|
Bot docker image hash |
name - String
|
|
reference - String
|
Bot manifest IPFS reference |
repository - String
|
Bot code repository url |
projects - [String]
|
Projects the bot monitors |
scanNodes - [String]
|
List of scanNodes running the bot |
version - String
|
Example
{
"chainIds": ["abc123"],
"createdAt": "xyz789",
"description": "xyz789",
"developer": "abc123",
"docReference": "abc123",
"enabled": false,
"id": "xyz789",
"image": "abc123",
"name": "abc123",
"reference": "abc123",
"repository": "abc123",
"projects": ["xyz789"],
"scanNodes": ["xyz789"],
"version": "abc123"
}
BotEndCursor
Fields
Field Name | Description |
---|---|
createdAt - String
|
Example
{"createdAt": "xyz789"}
BotEndCursorInput
Description
Search after specified bot createdAt
Fields
Input Field | Description |
---|---|
createdAt - Timestamp
|
Example
{"createdAt": 1592577642}
BotInfo
BotPageInfo
Fields
Field Name | Description |
---|---|
endCursor - BotEndCursor
|
|
hasNextPage - Boolean
|
|
totalBots - TotalMetadata!
|
Example
{
"endCursor": BotEndCursor,
"hasNextPage": false,
"totalBots": TotalMetadata
}
BotsInput
Description
Bot list input
Fields
Input Field | Description |
---|---|
after - BotEndCursorInput
|
Search results after the specified cursor |
first - NonNegativeInt
|
Indicate max number of results. |
ids - [String]
|
Filter bots by bot Ids. |
name - String
|
Filter bots by bot name. Case insensitive partial match. |
developer - String
|
Filter bots by developer checksum address. |
createdAtSortDirection - Sort
|
Indicate sorting order by bot createdAt 'desc' or 'asc'. Default is 'desc'. |
enabled - Boolean
|
Filter bots by enabled flag. |
Example
{
"after": BotEndCursorInput,
"first": 123,
"ids": ["xyz789"],
"name": "abc123",
"developer": "abc123",
"createdAtSortDirection": "asc",
"enabled": true
}
BotsResponse
Fields
Field Name | Description |
---|---|
bots - [Bot]
|
|
pageInfo - BotPageInfo
|
Example
{
"bots": [Bot],
"pageInfo": BotPageInfo
}
Contacts
Description
Project Contact Information
Fields
Field Name | Description |
---|---|
generalEmailAddress - EmailAddress
|
General contact email |
securityEmailAddress - EmailAddress
|
Security contact email |
Example
{
"generalEmailAddress": "test@test.com",
"securityEmailAddress": "test@test.com"
}
Contract
DateRange
Description
Date range Date format: YYYY-MM-DD
Fields
Input Field | Description |
---|---|
startDate - LocalDate!
|
|
endDate - LocalDate!
|
Example
{
"startDate": "2020-07-19",
"endDate": "2020-07-19"
}
DateTime
Description
A date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the date-time
format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
Example
"2007-12-03T10:15:30Z"
EmailAddress
Description
A field whose value conforms to the standard internet email address format as specified in RFC822: https://www.w3.org/Protocols/rfc822/.
Example
"test@test.com"
Float
Description
The Float
scalar type represents signed double-precision fractional values as specified by IEEE 754.
Example
123.45
Int
Description
The Int
scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
987
JSONObject
Description
The JSONObject
scalar type represents JSON objects as specified by ECMA-404.
Example
{}
Label
Description
Label information
Example
{
"label": "abc123",
"confidence": 123.45,
"entity": "xyz789",
"entityType": "abc123",
"remove": false,
"metadata": ["xyz789"]
}
LabelEndCursor
Fields
Field Name | Description |
---|---|
pageToken - String
|
Example
{"pageToken": "abc123"}
LabelEndCursorInput
Description
Search after specified pageToken
Fields
Input Field | Description |
---|---|
pageToken - String!
|
Example
{"pageToken": "abc123"}
LabelEvent
Description
Label event information
Fields
Field Name | Description |
---|---|
id - String
|
Unique string to identify this specific label event |
label - Label
|
The label payload |
source - LabelSource
|
Properties of the source information for this label |
createdAt - String
|
Timestamp when this label was added to Forta |
Example
{
"id": "abc123",
"label": Label,
"source": LabelSource,
"createdAt": "abc123"
}
LabelPageInfo
Fields
Field Name | Description |
---|---|
endCursor - LabelEndCursor!
|
|
hasNextPage - Boolean!
|
Example
{"endCursor": LabelEndCursor, "hasNextPage": true}
LabelSource
Fields
Field Name | Description |
---|---|
bot - BotInfo
|
|
alertHash - String
|
|
alertId - String
|
|
id - String
|
|
chainId - NonNegativeInt
|
Example
{
"bot": BotInfo,
"alertHash": "abc123",
"alertId": "xyz789",
"id": "xyz789",
"chainId": 123
}
LabelsInput
Description
Labels input
Fields
Input Field | Description |
---|---|
entities - [String]
|
Indicate a list of entities. Labels returned will only includes these entities |
labels - [String]
|
Indicate a list of labels. Labels returned will only includes these labels |
sourceIds - [String]
|
Indicate a list of sourceIds. Labels returned will only includes these sourceIds |
chainIds - [NonNegativeInt]
|
Indicate a list of chainIds. Labels returned will only includes these chainIds |
entityType - String
|
Indicate an entityType. Labels returned will only includes this entityType |
metadata - JSONObject
|
Indicate a map of key-value pairs Labels returned will have a metadata entry matching ALL of these pairs The map should be a basic map with only keys and string/numeric values (no objects) |
excludedMetadata - JSONObject
|
Indicate a map of key-value pairs Labels returned will have a metadata entry NOT matching ANY of these pairs The map should be a basic map with only keys and string/numeric values (no objects) |
createdSince - NonNegativeInt
|
Indicate earliest timestamp (in milliseconds). Labels returned will be created since this date. |
createdBefore - NonNegativeInt
|
Indicate latest timestamp (in milliseconds). Labels returned will be created before this date. |
afterCreatedAtDate - String
|
Indicate earliest timestamp (in RFC3339 format). Labels returned will be created after this date. |
beforeCreatedAtDate - String
|
Indicate latest timestamp (in RFC3339 format). Labels returned will be created before this date. |
after - LabelEndCursorInput
|
Search results after the specified cursor |
first - NonNegativeInt
|
Indicate max number of results. |
state - Boolean
|
Indicate true if only current state is desired |
Example
{
"entities": ["abc123"],
"labels": ["abc123"],
"sourceIds": ["abc123"],
"chainIds": [123],
"entityType": "xyz789",
"metadata": {},
"excludedMetadata": {},
"createdSince": 123,
"createdBefore": 123,
"afterCreatedAtDate": "abc123",
"beforeCreatedAtDate": "xyz789",
"after": LabelEndCursorInput,
"first": 123,
"state": false
}
LabelsResponse
Fields
Field Name | Description |
---|---|
labels - [LabelEvent]
|
|
pageInfo - LabelPageInfo
|
Example
{
"labels": [LabelEvent],
"pageInfo": LabelPageInfo
}
LocalDate
Description
A local date string (i.e., with no associated timezone) in YYYY-MM-DD
format, e.g. 2020-01-01
.
Example
"2020-07-19"
NonNegativeInt
Description
Integers that will have a value of 0 or more.
Example
123
Project
Description
Web3 Project Information
Example
{
"contacts": Contacts,
"name": "xyz789",
"id": "xyz789",
"social": Social,
"token": Token,
"website": "xyz789"
}
ProjectEdge
ProjectPageInfo
Fields
Field Name | Description |
---|---|
endCursor - String
|
|
hasNextPage - Boolean
|
|
totalProjects - TotalMetadata!
|
Example
{
"endCursor": "xyz789",
"hasNextPage": true,
"totalProjects": TotalMetadata
}
ProjectsInput
ProjectsResponse
Fields
Field Name | Description |
---|---|
edges - [ProjectEdge]
|
|
pageInfo - ProjectPageInfo
|
Example
{
"edges": [ProjectEdge],
"pageInfo": ProjectPageInfo
}
Relation
Values
Enum Value | Description |
---|---|
|
|
|
Example
"eq"
Social
Description
Social Media Links
Example
{
"coingecko": "xyz789",
"everest": "abc123",
"github": "abc123",
"twitter": "xyz789"
}
Sort
Values
Enum Value | Description |
---|---|
|
|
|
Example
"asc"
SourceAlertEvent
Description
Source alert information
Fields
Field Name | Description |
---|---|
hash - String
|
Alert hash |
botId - String
|
Bot id |
timestamp - String
|
Alert timestamp |
chainId - NonNegativeInt
|
Chain id |
Example
{
"hash": "abc123",
"botId": "abc123",
"timestamp": "abc123",
"chainId": 123
}
String
Description
The String
scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Example
"abc123"
Timestamp
Description
The javascript Date
as integer. Type represents date and time as number of milliseconds from start of UNIX epoch.
Example
1592577642
TimestampRange
Description
Timestamp range Timestamp format: number of milliseconds from start of UNIX epoch
Fields
Input Field | Description |
---|---|
startTimestamp - Timestamp!
|
|
endTimestamp - Timestamp!
|
Example
{"startTimestamp": 1592577642, "endTimestamp": 1592577642}
Token
Description
Project Token Information
Example
{
"address": "xyz789",
"chainId": 987,
"decimals": 123,
"name": "abc123",
"symbol": "abc123"
}
TotalMetadata
Description
Metadata about the number of matching items
Fields
Field Name | Description |
---|---|
value - NonNegativeInt!
|
Total number of matching documents. |
relation - Relation!
|
Indicates whether the number of matching items in the value parameter is accurate or a lower bound. |
Example
{"value": 123, "relation": "eq"}
scanNodeFilters
Description
Filter by number of scan nodes confirming the alert.
Fields
Input Field | Description |
---|---|
gte - NonNegativeInt
|
|
lte - NonNegativeInt
|
Example
{"gte": 123, "lte": 123}