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

Queries

`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": "abc123",
      "createdAt": "xyz789",
      "chainId": 123,
      "scanNodeId": "abc123",
      "receiptId": "xyz789"
    }
  }
}

Queries

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

Queries

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

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

Response

{
  "data": {
    "project": {
      "contacts": Contacts,
      "name": "xyz789",
      "id": "abc123",
      "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

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

Example

{
  "alertId": "abc123",
  "addresses": ["xyz789"],
  "contracts": [Contract],
  "createdAt": "abc123",
  "description": "abc123",
  "hash": "abc123",
  "metadata": {},
  "name": "xyz789",
  "projects": [Project],
  "protocol": "xyz789",
  "scanNodeCount": 123,
  "severity": "abc123",
  "source": AlertSource,
  "findingType": "xyz789",
  "alertDocumentType": "xyz789",
  "relatedAlerts": ["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!`
`totalAlerts` - `TotalMetadata!`

Example

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

Types

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
}

Types

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.

Example

{
  "addresses": ["xyz789"],
  "after": AlertEndCursorInput,
  "alertId": "abc123",
  "alertIds": ["abc123"],
  "alertHash": "xyz789",
  "alertName": "abc123",
  "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": "abc123"
}

Types

AlertsResponse

Fields

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

Example

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

Types

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": "xyz789",
  "createdAt": "xyz789",
  "chainId": 123,
  "scanNodeId": "xyz789",
  "receiptId": "xyz789"
}

Types

BatchEndCursor

Fields

Field Name	Description
`createdAt` - `String`

Example

{"createdAt": "abc123"}

Types

BatchEndCursorInput

Description

Search after specified batch after id

Fields

Input Field	Description
`createdAt` - `DateTime`

Example

{"createdAt": "2007-12-03T10:15:30Z"}

Types

BatchPageInfo

Fields

Field Name	Description
`endCursor` - `BatchEndCursor`
`hasNextPage` - `Boolean`
`totalBatches` - `TotalMetadata!`

Example

{
  "endCursor": BatchEndCursor,
  "hasNextPage": true,
  "totalBatches": TotalMetadata
}

Types

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": "xyz789",
  "receiptId": "abc123",
  "chainId": 123,
  "first": 123,
  "createdRange": TimestampRange
}

Types

BatchesResponse

Fields

Field Name	Description
`batches` - `[Batch]`
`pageInfo` - `BatchPageInfo`

Example

{
  "batches": [Batch],
  "pageInfo": BatchPageInfo
}

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

Types

BotEndCursor

Fields

Field Name	Description
`createdAt` - `String`

Example

{"createdAt": "xyz789"}

Types

BotEndCursorInput

Description

Search after specified bot createdAt

Fields

Input Field	Description
`createdAt` - `Timestamp`

Example

{"createdAt": 1592577642}

Types

BotPageInfo

Fields

Field Name	Description
`endCursor` - `BotEndCursor`
`hasNextPage` - `Boolean`
`totalBots` - `TotalMetadata!`

Example

{
  "endCursor": BotEndCursor,
  "hasNextPage": true,
  "totalBots": TotalMetadata
}

Types

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": "abc123",
  "createdAtSortDirection": "asc",
  "enabled": true
}

Types

BotsResponse

Fields

Field Name	Description
`bots` - `[Bot]`
`pageInfo` - `BotPageInfo`

Example

{
  "bots": [Bot],
  "pageInfo": BotPageInfo
}

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

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"

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

Types

ProjectEdge

Fields

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

Example

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

Types

ProjectPageInfo

Fields

Field Name	Description
`endCursor` - `String`
`hasNextPage` - `Boolean`
`totalProjects` - `TotalMetadata!`

Example

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

Types

ProjectsInput

Fields

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

Example

{"first": 987, "after": "xyz789"}

Types

ProjectsResponse

Fields

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

Example

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

Types

Relation

Values

Enum Value	Description
`eq`
`gte`

Example

"eq"

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

Types

Sort

Values

Enum Value	Description
`asc`
`desc`

Example

"asc"

Types

SourceAlertEvent

Description

Source alert information

Fields

Field Name	Description
`hash` - `String`	Alert hash
`botId` - `String`	Bot id
`timestamp` - `String`	Alert timestamp

Example

{
  "hash": "xyz789",
  "botId": "xyz789",
  "timestamp": "xyz789"
}

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

Timestamp

Description

The javascript Date as integer. Type represents date and time as number of milliseconds from start of UNIX epoch.

Example

1592577642

Types

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}

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": "abc123",
  "chainId": 987,
  "decimals": 987,
  "name": "abc123",
  "symbol": "abc123"
}

Types

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

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}