logo
Documentation Powered by ReDoc

MythX API (v1.4)

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.

API Authentication Methods

MythX API implements JWT and MetaMask authentication schemes. For better security user credentials (User ID / Ethereum address / email + password) are only used to start JWT sessions

JWT

The JSON Web Tokens authentication works this way:

  • Use POST /auth/login to generate a pair of JWT access and refresh tokens, and thus to start a JWT session.
  • To authenticate following API calls pass the access token, prefixed by Bearer label, inside the request's Authorization header; e.g. Authorization: Bearer JWT_ACCESS_TOKEN.
  • Access tokens are valid for ten minutes. To check a token's expiration timestamp decode the token, and check its exp value. Use POST /auth/refresh to refresh a JWT pair. Refresh tokens have one month expiration time.
  • To invalidate active JWT pair, and thus to terminate a JWT session use POST /auth/logout.
Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

MetaMask

Authentication scheme for MetaMask.

  • Get authentication challenge with GET /auth/challenge;
  • Sign it with MetaMask;
  • Pass the signed message via the Authorization HTTP header of the next request to a protected API endpoint. The header value must follow the format MetaMask SIGNED_CHALLENGE.
Security scheme type: HTTP
HTTP Authorization Scheme digest

Authentication Calls

Auth challenge

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

  • Challenge based on Ethereum address. Generated when ethAddress query parameter is provided.
query Parameters
ethAddress
string <Ethereum address>

A valid Ethereum address.

type
string
Default: "one_time"
Enum:"one_time" "short_lived"

Type of the challenge to generate.

  • one_time allows just a single use of challenge response for authentication of a subsequent API call, within 24 hours after generation of the challenge. After the first use the challenge is revoked. It is also revoked if not used within the 24 hours.

  • short_lived allows to use the challenge response unlimited number of times within 10 minutes after the challenge generation.

Responses

200

Returns two objects describing the banner to be shown in the MetaMask dialog and the challenge hash.

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /auth/challenge
https://api.mythx.io/v1/auth/challenge

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    }
]

API login

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 (either userId + password, or ethAddress + password).

Authorizations:
MetaMask
Request Body schema: application/json
One of
  • Login with User Credentials
  • Login with MetaMask
password
required
string <password>

User password.

A valid password is:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
ethAddress
string <Ethereum address.>

User Ethereum address.

userId
string <MongoDB ID>

User ID.

Responses

200

Login successful

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/login
https://api.mythx.io/v1/auth/login

Request samples

Content type
application/json
Example
Login with User Credentials
Copy
 Expand all Collapse all
{
  • "password": "pa$$word",
  • "ethAddress": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "jwtTokens":
    {
    },
  • "access": "string",
  • "refresh": "string"
}

API logout

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.

Authorizations:
JWT
Request Body schema: application/json
global
boolean
Default: false

If true all JWT tokens associated with the user will be revoked.

Responses

200

Logged out successfully

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/logout
https://api.mythx.io/v1/auth/logout

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "global": false
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Refresh Auth Tokens

Generates a new pair of JWT authentication tokens (access and refresh), and revokes the current one.

Request Body schema: application/json
jwtTokens
object (JWT Tokens)

Holds a pair of JWT authentication tokens.

accessToken
string
Deprecated

JWT access token.

refreshToken
string
Deprecated

JWT refresh token.

Responses

200

Tokens refreshed successfully

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/refresh
https://api.mythx.io/v1/auth/refresh

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "jwtTokens":
    {
    },
  • "accessToken": "string",
  • "refreshToken": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "jwtTokens":
    {
    },
  • "access": "string",
  • "refresh": "string"
}

Security Analysis

List Past Analyses

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

Example Date Strings

  • 2018-11-20,
  • 2018-11-20T23:13:12,
  • 2018-11-20T23:13:12+00:00
  • 2018-11-20T23:13:12.177Z
Authorizations:
JWT
query Parameters
offset
integer <int32>
Default: 0

Pagination offset. Number of records to skip.

dateFrom
string <date-time> Nullable

Submission time filter. Restricts results to analyses submitted after this time. Unset by default.

dateTo
string <date-time> Nullable

Submission time filter. Restricts results to analyses submitted before this time. Unset by default.

Responses

200

Success

400

Bad Request — Likely invalid schema in analysis-request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /analyses
https://api.mythx.io/v1/analyses

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "total": 2,
  • "analyses":
    [
    ]
}

Submit Smart Contract for analysis

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

with the exception of the following field name changes which follow Truffe conventions:

  • bin → bytecode
  • bin-runtime → deployedBytecode
  • srcmap → sourceMap
  • srcmap-runtime → deployedSourceMap
Authorizations:
JWTMetaMask
Request Body schema: application/json
clientToolName
string

Optional. Name of the client tool sending the request.

noCacheLookup
boolean

Optional. If true API will not look into the cache of past analyses, and always will run a new analysis for this request. Note that using the cache has no side effect beside saving the runtime, thus this option MUST NOT be used in any case beside API testing (e.g. to benchmark current queue time for a previously done analysis).

data
required
Compete Analysis (object) or Bytecode Only (object) or Sourcecode Only (object)

Expand data to view full schema.

Responses

200

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.
400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

413

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.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /analyses
https://api.mythx.io/v1/analyses

Request samples

Content type
application/json
Example
Complete Analysis
Copy
 Expand all Collapse all
{
  • "clientToolName": "Sample MythX Client",
  • "noCacheLookup": true,
  • "data":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "apiVersion": "v1.3.0",
  • "harveyVersion": "v0.1.0",
  • "maestroVersion": "v1.1.4",
  • "maruVersion": "v0.2.0",
  • "mythrilVersion": "0.19.11",
  • "queueTime": 0,
  • "status": "Queued",
  • "submittedAt": "2019-01-10T01:29:38.410Z",
  • "submittedBy": "000008544b0aa00010a91111",
  • "uuid": "0680a1e2-b908-4c9a-a15b-636ef9b61486"
}

Analysis Status

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.

Authorizations:
JWTMetaMask
path Parameters
uuid
required
string <uuid>

analysis id

Responses

200

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.
400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

404

Not Found

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /analyses/{uuid}
https://api.mythx.io/v1/analyses/{uuid}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "apiVersion": "string",
  • "clientToolName": "string",
  • "error": "string",
  • "harveyVersion": "string",
  • "maestroVersion": "string",
  • "maruVersion": "string",
  • "mythrilVersion": "string",
  • "queueTime": 0,
  • "runTime": 0,
  • "status": "Queued",
  • "submittedAt": "2019-07-19T16:04:40Z",
  • "submittedBy": "string",
  • "uuid": "string"
}

Analysis Input

Returns the input of a past analysis.

Authorizations:
JWTMetaMask
path Parameters
uuid
required
string <uuid>

analysis id

Responses

200

Success. Returns requested input.

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

403

Forbidden — Request is not allowed to the authenticated user due to a lack of permissions.

404

Not Found

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /analyses/{uuid}/input
https://api.mythx.io/v1/analyses/{uuid}/input

Response samples

Content type
application/json
Example
Complete Analysis
Copy
 Expand all Collapse all
{
  • "bytecode": "0x6080604052602060405190810160405280600060010260001916600019168152506000906001610030929190610043565b5034801561003d57600080fd5b506100bb565b828054828255906000526020600020908101928215610085579160200282015b82811115610084578251829060001916905591602001919060010190610063565b5b5090506100929190610096565b5090565b6100b891905b808211156100b457600081600090555060010161009c565b5090565b90565b60d8806100c96000396000f300608060405260043610603f576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063017a9105146044575b600080fd5b348015604f57600080fd5b50606c60048036038101908080359060200190929190505050608a565b60405180826000191660001916815260200191505060405180910390f35b600081815481101515609857fe5b9060005260206000200160009150905054815600a165627a7a72305820d1c4ab8874b5f3cc139613c225a5908ed916e813f5ccdf9a9de97ce28420ca090029",
  • "mainSource": "PublicStorageArray.sol",
  • "sources":
    {
    }
}

Detected issues

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.

IMPORTANT NOTE: Due to technical constraints, for some results the creation bytecode hash is returned inside the source list - instead of the original filename. Results concerning this hash can safely be excluded if they do not provide any additional value. This case usually happens when code is dynamically generated, e.g. inside the given contract's constructor.

Authorizations:
JWTMetaMask
path Parameters
uuid
required
string <uuid>

analysis id

Responses

200

Success

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

404

Not Found

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /analyses/{uuid}/issues
https://api.mythx.io/v1/analyses/{uuid}/issues

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

User Accounts

List of users

Lists registered API users. Allows to lookup users by email and Ethereum addresses.

For users with no USER_LOOKUP permission this endpoint only finds their own user objects.

Returns at most 20 users in a single response. Use the offset query parameter for pagination.

Authorizations:
JWTMetaMask
query Parameters
offset
integer
Default: 0

Pagination offset. The number of records to skip.

orderBy
string
Default: "email"
Value:"email"

User ordering.

email
string
Default: null

Filter user by email fragment.

ethAddress
string
Default: null

Filter users by Ethereum address fragments.

Responses

200

Success

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /users
https://api.mythx.io/v1/users

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "total": 0,
  • "users":
    [
    ]
}

Create a new user

Creates a new user.

  • Creation of a new user by a parent user.

    The parent user must have necessary permissions (GET /v1/users/{id}/permissions). Currently, CREATE_USERS_ADMIN, CREATE_USERS_FREE, CREATE_USERS_PROFESSIONAL, CREATE_USER_PREMIUM, CREATE_USERS_TRUSTED, and CREATE_USERS_WITHOUT_ROLES permissions allow to create users with corresponding roles, as well as further give and take corresponding roles of created users.

    The only obligatory request field is the password to set on the created user account.

  • Self-registration

    • With MetaMask

      This endpoint allows users to self-register at MythX Website. In this case it is obligatory to use the MetaMask authentication scheme, and provide at least the following required parameters: password (to set on the created user account), termsId, and gReCaptcha.

      email, if provided, must be unique among registered users. It won't be used by API until verification (the exact details to be added).

Authorizations:
MetaMask
Request Body schema: application/json
One of
  • Create User
  • Self-Registration With MetaMask
password
required
string <password>

User password.

A valid password is:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
email
string <email>

Email. Must be unique among already registered users.

ethAddress
string <Ethereum Address>

User's ethereum address.

label
string <= 256 characters

Optional label, visible to the user, and editable by the user. It is also exposed to the users created by this user as creatorLabel field in their user objects.

ownerPartnerId
string <MongoDB ObjectID>

ID of the partner account associated with this user. Analyses executed by the newly created user will be counted for that parnter for billing and book-keeping purposes.

Requires SET_USER_OWNER_PARNTER_ID permission to set.

privateLabel
string <= 256 characters

Optional label, invisible to the user. This label is only visible to, and editable by MythX admins, and also to users up in the user tree (i.e. those who created this user, those who created them, etc.)

preferences
object (User Preferences)

Generic user preferences.

roles
Array of strings

The following user roles exist in MythX plaform as of now:

  • admin - Gives all possible permissions. It is only intended for core members of MythX team.

  • Free - Gives permission for regular API usage. Currently it means the allowance to send up to 1k analyses in any 24h period.

  • partner - Gives permission to create new privileged and regular users.

  • Professional - Currently not in use. Will take the current Free role's permissions after the launch, and decrease of Free role allowances.

  • Premium - Gives permission for premium API usage. Currently it means the allowance to send up to 10k analyses in any 24h period. Mind that currently there is an additional limit for everybody: at most 100 non-finished analyses per user at any time.

  • shared_user - Gives permission to expirience all usage limits on per-IP basis. This is intended for trial users only.

  • trusted_user - Gives permission to fetch internal platform usage statistics.

Responses

201

Returns created user object.

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /users
https://api.mythx.io/v1/users

Request samples

Content type
application/json
Example
Create User
Copy
 Expand all Collapse all
{
  • "password": "pa$$word",
  • "email": "user@example.com",
  • "ethAddress": "string",
  • "label": "string",
  • "ownerPartnerId": "string",
  • "privateLabel": "string",
  • "preferences":
    {
    },
  • "roles":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "createdAt": "2019-07-19",
  • "createdBy": "string",
  • "createdByPartner": true,
  • "creatorLabel": "",
  • "email":
    {
    },
  • "ethAddress": "string",
  • "label": "string",
  • "ownerPartnerId": "string",
  • "ownerPartnerLabel": "",
  • "privateLabel": "string",
  • "preferences":
    {
    },
  • "roles":
    [
    ],
  • "subscriptionId": "string",
  • "termsId": "no_terms"
}

User Object By ID

Gets user object by user ID.

Authorizations:
JWTMetaMask
path Parameters
id
required
string <MongoDB Object ID>

User ID.

Responses

200

Success. Returns requested user object.

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

403

Forbidden — Request is not allowed to the authenticated user due to a lack of permissions.

429

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.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /users/{id}
https://api.mythx.io/v1/users/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "createdAt": "2019-07-19",
  • "createdBy": "string",
  • "createdByPartner": true,
  • "creatorLabel": "",
  • "email":
    {
    },
  • "ethAddress": "string",