Forta API GraphQL API Reference

Free GraphQL API access to alerts and blockchain projects data

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

Response

Returns a Batch

Arguments
Name Description
id - String!

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

Response

Returns a Project

Arguments
Name Description
id - String!

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

Fields
Field Name Description
image - String
imageHash - String
id - String
manifest - String
Example
{
  "image": "abc123",
  "imageHash": "abc123",
  "id": "xyz789",
  "manifest": "xyz789"
}

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

Description

Smart Contract Information

Fields
Field Name Description
address - String! EIP55 checksummed deployment address
name - String! User-friendly name of the contract
projectId - String! Related web3 project
Example
{
  "address": "abc123",
  "name": "abc123",
  "projectId": "xyz789"
}

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

Fields
Field Name Description
label - String Label name
confidence - Float Label confidence
entity - String Label's entity
entityType - String Label's entity type
remove - Boolean Label's status
metadata - [String] Extra 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

Fields
Field Name Description
contacts - Contacts List of contact info
name - String! User-friendly name of the project
id - String! Project identifier
social - Social
token - Token
website - String Main website of the project
Example
{
  "contacts": Contacts,
  "name": "xyz789",
  "id": "xyz789",
  "social": Social,
  "token": Token,
  "website": "xyz789"
}

ProjectEdge

Fields
Field Name Description
cursor - String
node - Project
Example
{
  "cursor": "xyz789",
  "node": Project
}

ProjectPageInfo

Fields
Field Name Description
endCursor - String
hasNextPage - Boolean
totalProjects - TotalMetadata!
Example
{
  "endCursor": "xyz789",
  "hasNextPage": true,
  "totalProjects": TotalMetadata
}

ProjectsInput

Fields
Input Field Description
first - Int
after - String
Example
{"first": 987, "after": "xyz789"}

ProjectsResponse

Fields
Field Name Description
edges - [ProjectEdge]
pageInfo - ProjectPageInfo
Example
{
  "edges": [ProjectEdge],
  "pageInfo": ProjectPageInfo
}

Relation

Values
Enum Value Description

eq

gte

Example
"eq"

Social

Description

Social Media Links

Fields
Field Name Description
coingecko - String Path to the coingecko identifier
everest - String Identifier in the everest.link registry
github - String Github organization slug
twitter - String Twitter account name
Example
{
  "coingecko": "xyz789",
  "everest": "abc123",
  "github": "abc123",
  "twitter": "xyz789"
}

Sort

Values
Enum Value Description

asc

desc

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

Fields
Field Name Description
address - String! Address where the project token is deployed
chainId - Int! EIP155 identifier of the chain where the project token is deployed
decimals - Int Decimals of the token contract
name - String Name of the token
symbol - String Symbol of the token
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}