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
    }
  }
}

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": "abc123"}
Response
{
  "data": {
    "project": {
      "contacts": Contacts,
      "name": "xyz789",
      "id": "xyz789",
      "social": Social,
      "token": Token,
      "website": "xyz789"
    }
  }
}

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

Agent

Description

(Deprecated - will remove 6/1/2022) Agent information

Fields
Field Name Description
id - String Agent id
reference - String Agent manifest reference
image - String Agent docker image url
Example
{
  "id": "xyz789",
  "reference": "abc123",
  "image": "xyz789"
}

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": "xyz789",
  "description": "abc123",
  "hash": "xyz789",
  "metadata": {},
  "name": "abc123",
  "projects": [Project],
  "protocol": "abc123",
  "scanNodeCount": 987,
  "severity": "xyz789",
  "source": AlertSource,
  "findingType": "abc123"
}

AlertEndCursor

Fields
Field Name Description
blockNumber - NonNegativeInt!
alertId - String!
Example
{"blockNumber": 123, "alertId": "abc123"}

AlertEndCursorInput

Description

Search after specified block number and alertId

Fields
Input Field Description
blockNumber - NonNegativeInt!
alertId - String!
Example
{"blockNumber": 123, "alertId": "abc123"}

AlertPageInfo

Fields
Field Name Description
endCursor - AlertEndCursor!
hasNextPage - Boolean!
Example
{"endCursor": AlertEndCursor, "hasNextPage": true}

AlertSource

Description

Source where the threat was detected

Fields
Field Name Description
transactionHash - String Transaction where the threat was detected
agent - Agent Agent that triggered the alert Use 'bot'.
bot - Bot Bot that triggered the alert
block - Block Block where the threat was detected
Example
{
  "transactionHash": "abc123",
  "agent": Agent,
  "bot": Bot,
  "block": Block
}

AlertsInput

Description

Alert list input

Fields
Input Field Description
after - AlertEndCursorInput

Search results after the specified cursor

addresses - [String]

Indicate a list of addresses. Alerts returned will have those addresses involved.

bots - [String]

Indicate a list of bot hashes. Alerts returned will only be from any of those bots.

blockNumberRange - BlockRange

Block number range Alerts for the block number range will be returned.

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.

blockDateRange - DateRange

Block Date range Alerts returned will be between the specified start and end block timestamp dates when the threats were detected.

first - NonNegativeInt

Indicate max number of results.

projectId - String

Indicate a project Id. Alerts returned will only be from that project.

blockSortDirection - Sort

Indicate sorting order by block number, 'desc' or 'asc'. Default is 'desc'.

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
{
  "after": AlertEndCursorInput,
  "addresses": ["abc123"],
  "bots": ["xyz789"],
  "blockNumberRange": BlockRange,
  "chainId": 123,
  "createdSince": 123,
  "blockDateRange": DateRange,
  "first": 123,
  "projectId": "xyz789",
  "blockSortDirection": "asc",
  "scanNodeConfirmations": scanNodeFilters,
  "severities": ["xyz789"],
  "transactionHash": "xyz789"
}

AlertsResponse

Fields
Field Name Description
alerts - [Alert]
pageInfo - AlertPageInfo
Example
{
  "alerts": [Alert],
  "pageInfo": AlertPageInfo
}

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
id - String Bot id
reference - String Bot manifest reference
image - String Bot docker image url
Example
{
  "id": "xyz789",
  "reference": "abc123",
  "image": "xyz789"
}

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

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

ProjectEdge

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

ProjectPageInfo

Fields
Field Name Description
endCursor - String
hasNextPage - Boolean
Example
{
  "endCursor": "abc123",
  "hasNextPage": false
}

ProjectsInput

Fields
Input Field Description
first - Int
after - String
Example
{"first": 123, "after": "abc123"}

ProjectsResponse

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

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

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"

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

scanNodeFilters

Description

Filter by number of scan nodes confirming the alert.

Fields
Input Field Description
gte - NonNegativeInt
lte - NonNegativeInt
Example
{"gte": 123, "lte": 123}