Download OpenAPI specification:Download
MythX is a security analysis API for Ethereum smart contracts. It powers tools that bring security into the smart contract SDLC.
Join the MythX community at MythX Discord for more information.
This document describes the API interface to MythX. It is entended for Dapp developers who wish to bring the power MythX to their Dapps.
Contents:
Note that the interface is still evolving.
HTTP requests to protected API endpoints must be signed by
JWT access token. Use POST /auth/login to generate
JWT access and refresh tokens,
POST /auth/refresh to refresh the tokens,
and POST /auth/logout to close the session. The
access token must be passed in the header format
Authorization: Bearer <access token>.
| Security scheme type: | HTTP |
|---|---|
| HTTP Authorization Scheme | Bearer |
Authentication scheme for MetaMask.
MetaMask <SIGNED MESSAGE>.| Security scheme type: | HTTP |
|---|---|
| HTTP Authorization Scheme | Digest |
Generates authentication challenge.
At least one of query parameters must be provided, and it will determine the type of challenge to generate. Currently, only challenges based on Ethereum address of the user are supported, for MetaMask authentication scheme. Additional challenge types might be added in future.
Challenge Types
| ethAddress | string <Ethereum address> A valid Ethereum address. |
| type | string Default: "one_time" Enum:"one_time" "short_lived" Type of the challenge to generate.
|
Returns two objects describing the banner to be shown in the MetaMask dialog and the challenge hash.
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Generates a pair of access and refresh JWT tokens for JWT authentication scheme.
Supports the following modes of operation:
MetaMask login - use MetaMask authentication to get JWT tokens. Does not require any body parameters.
User credentials login - provide a pair of user credentials in the request body (ethAddress + password).
Login successful
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Closes the current API session, revoking JWT access token that signs this request, and the corresponding refresh token. Optional global parameter allows to close all user's sessions.
| global | boolean Default: false If true all JWT tokens associated with the user will be revoked. |
Logged out successfully
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Generates a new pair of JWT authentication tokens (access and refresh), and revokes the current one.
| jwtTokens | object (JWT Tokens) Holds a pair of JWT authentication tokens. |
| accessToken | string Deprecated JWT access token. |
| refreshToken | string Deprecated JWT refresh token. |
Tokens refreshed successfully
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Lists analyses visible to the user, at most 20 records a time, sorted by submission time from the most recent to the oldest ones. Use offset query parameter for results pagination. Use dateFrom and dateTo query parameters to filter by analysis submission timestamps.
Dates are specified using ann ISO 8601 Date string
2018-11-20,2018-11-20T23:13:12,2018-11-20T23:13:12+00:002018-11-20T23:13:12.177Z| offset | integer <int32> Default: 0 Pagination offset. Number of records to skip. |
| dateFrom | string <date-time> Default: null Submission time filter. Restricts results to analyses submitted after this time. |
| dateTo | string <date-time> Default: null Submission time filter. Restricts results to analyses submitted before this time. |
Success
Bad Request — Likely invalid schema in analysis-request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Submits Solidity contract(s) for vulnerability analysis and returns created analysis record. It is possible to conduct a partial analysis on a contract by only submitting its creation bytecode or its source code in their respective schema fields. Fill out both fields to conduct a complete analysis. The uuid field of the response should be used in subsequent calls to:
check analysis status, metadata, and the list of detected issues.
In addition to the JSON fields listed below, we allow additional fields. For example, truffle artfics will have an additional abi attribute.
The request format is equivalent to the output of:
$ solc --pretty-json --combined-json ast,bin,bin-runtime,srcmap,srcmap-runtimewith the exception of the following field name changes which follow Truffe conventions:
bin → bytecodebin-runtime → deployedBytecodesrcmap → sourceMapsrcmap-runtime → deployedSourceMap| clientToolName | string Optional. Name of the client tool sending the request. |
| noCacheLookup | boolean Optional. If |
| data required | object |
Analysis request received. Check the status field for request status.
It can be one of:
Queued: The analysis request is in a backlog queue of analysis requests to be processed.Finished: Analysis has finished. This can happen if the analysis is exactly the same as a prior
run, so results come the cached reports. Using the uuid field in the response, issue a request to the get the issue results using
another call to get Analysis results.Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
JSON data sent too large — Your request's body was larger than the maximum 5MB limit allowed by the server. Try to split your request into serveral ones.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Gets status and metadata of for a prior
submit Smart Contract analysis request.
In the submission, a uuid was returned, which should be used in the url for
this request.
When analysis status is Finished,
GET /analyses/{uuid}/issues may be
used to list detected vulnerabilities.
| uuid required | string <uuid> analysis id |
Analysis status request processed. Check the status field for request status.
It can be one of:
Queued: The analysis request is in a backlog queue of analysis requests to be processed.Running: The analysis request is currently running MythX analysis.Error: There was some error that terminated analysis processing. Check the error field for details about the problem.Finished: Analysis has finished. Using the uuid field in the response issue a request to the get the issue results using
another call to get Analysis results.Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Lists issues detected during the analysis specified by UUID. Request will fail for unfinished analyses, use GET /analyses/{uuid} to verify the current analysis status.
| uuid required | string <uuid> analysis id |
Success
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
Gets OpenAPI specification of Mythril API, in HTML format.
Success
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
HTML document with OpenAPI specification for Mythril API
Gets OpenAPI specification of Mythril API, in YAML format.
Success
Not Found — A non-existing endpoint hit.
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
YAML document with OpenAPI specification for Mythril API
Gets current versions of Mythril API and its core sub-modules.
Success
Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.