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

Queries

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

Queries

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

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

Types

AlertEndCursor

Fields

Field Name	Description
`blockNumber` - `NonNegativeInt!`
`alertId` - `String!`

Example

{"blockNumber": 123, "alertId": "abc123"}

Types

AlertEndCursorInput

Description

Search after specified block number and alertId

Fields

Input Field	Description
`blockNumber` - `NonNegativeInt!`
`alertId` - `String!`

Example

{"blockNumber": 123, "alertId": "abc123"}

Types

AlertPageInfo

Fields

Field Name	Description
`endCursor` - `AlertEndCursor!`
`hasNextPage` - `Boolean!`

Example

{"endCursor": AlertEndCursor, "hasNextPage": true}

Types

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
}

Types

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

Types

AlertsResponse

Fields

Field Name	Description
`alerts` - `[Alert]`
`pageInfo` - `AlertPageInfo`

Example

{
  "alerts": [Alert],
  "pageInfo": AlertPageInfo
}

Types

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
}

Types

BlockRange

Description

Block range

Fields

Input Field	Description
`startBlockNumber` - `NonNegativeInt!`
`endBlockNumber` - `NonNegativeInt!`

Example

{"startBlockNumber": 123, "endBlockNumber": 123}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

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

Types

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

Types

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

Types

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

Types

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

Types

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

Types

JSONObject

Description

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

Example

{}

Types

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"

Types

NonNegativeInt

Description

Integers that will have a value of 0 or more.

Example

Types

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

Types

ProjectEdge

Fields

Field Name	Description
`cursor` - `String`
`node` - `Project`

Example

{
  "cursor": "xyz789",
  "node": Project
}

Types

ProjectPageInfo

Fields

Field Name	Description
`endCursor` - `String`
`hasNextPage` - `Boolean`

Example

{
  "endCursor": "abc123",
  "hasNextPage": false
}

Types

ProjectsInput

Fields

Input Field	Description
`first` - `Int`
`after` - `String`

Example

{"first": 123, "after": "abc123"}

Types

ProjectsResponse

Fields

Field Name	Description
`edges` - `[ProjectEdge]`
`pageInfo` - `ProjectPageInfo`

Example

{
  "edges": [ProjectEdge],
  "pageInfo": ProjectPageInfo
}

Types

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

Types

Sort

Values

Enum Value	Description
`asc`
`desc`

Example

"asc"

Types

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"

Types

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

Types

scanNodeFilters

Description

Filter by number of scan nodes confirming the alert.

Fields

Input Field	Description
`gte` - `NonNegativeInt`
`lte` - `NonNegativeInt`

Example

{"gte": 123, "lte": 123}