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-protocol/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": "xyz789",
      "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
    }
  }
}

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": "abc123",
      "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

Example
{
  "alertId": "abc123",
  "addresses": ["abc123"],
  "contracts": [Contract],
  "createdAt": "abc123",
  "description": "abc123",
  "hash": "abc123",
  "metadata": {},
  "name": "xyz789",
  "projects": [Project],
  "protocol": "xyz789",
  "scanNodeCount": 123,
  "severity": "abc123",
  "source": AlertSource,
  "findingType": "abc123"
}

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": false,
  "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
Example
{
  "transactionHash": "abc123",
  "bot": Bot,
  "block": Block
}

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.

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.

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.

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.

Example
{
  "addresses": ["xyz789"],
  "after": AlertEndCursorInput,
  "alertId": "abc123",
  "alertHash": "abc123",
  "alertName": "xyz789",
  "blockDateRange": DateRange,
  "blockNumberRange": BlockRange,
  "blockTimestampRange": TimestampRange,
  "blockSortDirection": "asc",
  "bots": ["abc123"],
  "chainId": 123,
  "createdSince": 123,
  "first": 123,
  "projectId": "xyz789",
  "scanNodeConfirmations": scanNodeFilters,
  "severities": ["abc123"],
  "transactionHash": "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": "xyz789",
  "parentId": "abc123",
  "createdAt": "abc123",
  "chainId": 123,
  "scanNodeId": "xyz789",
  "receiptId": "xyz789"
}

BatchEndCursor

Fields
Field Name Description
createdAt - String
Example
{"createdAt": "abc123"}

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": "abc123",
  "scanNodeId": "xyz789",
  "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}

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": "abc123",
  "developer": "xyz789",
  "docReference": "xyz789",
  "enabled": true,
  "id": "xyz789",
  "image": "xyz789",
  "name": "abc123",
  "reference": "xyz789",
  "repository": "xyz789",
  "projects": ["abc123"],
  "scanNodes": ["xyz789"],
  "version": "abc123"
}

BotEndCursor

Fields
Field Name Description
createdAt - String
Example
{"createdAt": "abc123"}

BotEndCursorInput

Description

Search after specified bot createdAt

Fields
Input Field Description
createdAt - Timestamp
Example
{"createdAt": 1592577642}

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": ["abc123"],
  "name": "xyz789",
  "developer": "xyz789",
  "createdAtSortDirection": "asc",
  "enabled": false
}

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": "[email protected]",
  "securityEmailAddress": "[email protected]"
}

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": "xyz789",
  "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
"[email protected]"

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
123

JSONObject

Description

The JSONObject scalar type represents JSON objects as specified by ECMA-404.

Example
{}

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": "abc123",
  "id": "xyz789",
  "social": Social,
  "token": Token,
  "website": "abc123"
}

ProjectEdge

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

ProjectPageInfo

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

ProjectsInput

Fields
Input Field Description
first - Int
after - String
Example
{"first": 123, "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"

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
"xyz789"

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": 123,
  "decimals": 987,
  "name": "xyz789",
  "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}