API Documentation

The function and event signature database exposes a RESTful API that is provided free to use by anyone without restriction.

Authentication

There is no authentication necessary to access this API

Content Types

All api endpoints accept requests with the following content types unless specified otherwise.

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

Github Webhook Integration

The easiest way to help populate the database is with a github webook on your repository.

• Under the Webhooks & Services section in the repository settings, click the Add Webhook button.
• Use the url: https://www.4byte.directory/api/v1/receive-github-webhook/.
• Select the application/json content type.

Once configured, after each new git push or merged pull request, the site will pull down your codebase and parse all of the solidity files for function and event signatures

Importing Source Files

Solidity Imports /api/v1/import-solidity/ POST

This endpoint either solidity source files or the solidity source code itsel, parses it for function & event signatures and imports them.

Example Request for Source Import

{
  "source_code": "contract Wallet { function withdraw() { msg.sender.send(this.balance); } }"
}

Example Request for File Import

$ curl -F source_file=@/path/to/some/Contract.sol https://www.4byte.directory/api/v1/import-solidity/

Example Response

{
  "num_processed": 25,
  "num_imported": 3,
  "num_duplicates": 18,
  "num_ignored": 4
}

Content Types

When importing files multipart/form-data is accepted. Otherwise, all content types are accepted.

How to import a bunch of files

If you'd like to import many source files, you can do so with the following command line magic.

$ find /path/to/recursively/search/ -name *.sol | xargs -n 1 -I {} curl -F source_file=@{} https://www.4byte.directory/api/v1/import-solidity/

Importing from Contract ABI

You can import all of the function & event signatures from a contract by submitting the ABI

Example Request

{
  "contract_abi": '[
    {"constant":false,"inputs":[],"name":"f","outputs":[],"type":"function"},{"inputs":[],"type":"constructor"},
    {"anonymous":false,"inputs":[{"name":"", "type":"string", "indexed":true}],"name":"E","type":"event"}
  ]'
}

Example Response

{
  "num_processed": 4,
  "num_imported": 2,
  "num_duplicates": 1,
  "num_ignored": 1
}

Signatures

The primary data model exposed by the API is the Signature. Each signature is a mapping between the human readable function signature and the 4-byte function selector used by the EVM. See the official Ethereum Contract ABI documentation for more information.

Each signature object returned from the API has the following fields.

• id (integer): The primary key of the signature.
• text_signature (string): The text representation of the function signature.
• bytes_signature (string): The 4-byte function selector
• hex_signature (string): The hex encoded 4-byte function selector.

{
  "id": 1,
  "text_signature": "balanceOf(address)",
  "bytes_signature": "r'\x13\xf7",
  "hex_signature": "0x722713f7",
}

Listing Signatures /api/v1/signatures/ GET

Returns a paginated list of signatures.

Example Response

{
  "next": "/api/v1/signatures/?page=2",
  "previous": null,
  "count": 100,
  "results": [
    { 
      "id": 1,
      "text_signature": "balanceOf(address)",
      "bytes_signature": "r'\x13\xf7",
      "hex_signature": "0x722713f7",
    },
    ...
  ]
}

Response Status Codes

• 200 Success

Filtering Results

The following options are available for filtering the results

Filtering on text_signature

/api/v1/signatures/?text_signature=balanceOf()

Exact match on the text_signature field.

/api/v1/signatures/?text_signature__iexact

Case insensitive exact match on the text_signature field.

/api/v1/signatures/?text_signature__contains

Substring match on the text_signature field.

/api/v1/signatures/?text_signature__icontains

Case insensitive substring match on the text_signature field.

/api/v1/signatures/?text_signature__startswith

Matches on beginning of the text_signature field.

/api/v1/signatures/?text_signature__istartswith

Case insensitive match on beginning of the text_signature field.

/api/v1/signatures/?text_signature__endswith

Matches on end of the text_signature field.

/api/v1/signatures/?text_signature__iendswith

Case insensitive match on end of the text_signature field.

Filtering on hex_signature

Filters the results base on the hex_signature field.

/api/v1/signatures/?hex_signature=0xabcd1234

• If the provided query is exactly 4 bytes long then results are filtered by exact match.
• If the provided query is less than 4 bytes long then the results are filtered by substring match.
• If the provided query is longer than 4 bytes then the results are not filtered since it is an invalid query.

Creating Signatures /api/v1/signatures/ POST

Creates a new signature

Example Request

{
      "text_signature": "balanceOf(address)"
}

Response Status Codes

• 200 Success
• 400 Error

Example Success Response

On success, the serialized record will be returned

{
  "id": 1,
  "text_signature": "balanceOf(address)",
  "bytes_signature": "r'\x13\xf7",
  "hex_signature": "0x722713f7",
}

Accepted Formats for text_signature

Function signatures are normalized during creation. The normalization process can handle a wide array of input formats. Any of the following will normalize to transfer(address,uint256)

• function transfer(address _to, uint _value)
• function transfer(address _to, uint256 _value)
• transfer(address _to, uint256 _value)
• transfer(address _to, uint _value)
• transfer(address, uint)
• transfer(address, uint256)
• transfer ( address, uint256 )
• transfer ( address, uint256 )

Example Error Response

When an error occurs, the response will be an object with keys mapping to arrays of error messages. A 400 response will be returned if the signature is already present, or if the format of the signature could not be recognized.

{
      "text_signature": ["Unknown signature format"]
}

Retrieving Signatures /api/v1/signatures/:id/ GET

You can retrieve an individual signature using this endpoint.

Response Status Codes

• 200 Success
• 404 Not Found

Example Success Response

On success, the serialized record will be returned

{
  "id": 1,
  "text_signature": "balanceOf(address)",
  "bytes_signature": "r'\x13\xf7",
  "hex_signature": "0x722713f7",
}

Event Signatures

The API also exposes the signatures for events which are represented under the data model Event Signature. Each signature is a mapping between the human readable event signature and the 32-byte event selector used by the EVM. See the official Ethereum Contract ABI documentation for more information.

Each event signature object returned from the API has the following fields.

• id (integer): The primary key of the event signature.
• text_signature (string): The text representation of the event signature.
• bytes_signature (string): The 32-byte event selector
• hex_signature (string): The hex encoded 32-byte event selector.

{
  "id": 19,
  "created_at": "2020-09-13T18:45:58.559831Z",
  "text_signature": "RequestCreated(address,address,int256,uint256[12])",
  "hex_signature": "0x15aac4af776447c09d895192c86bab463c38b92191f3ba3f7b8831723c548d6e",
  "bytes_signature": "r'\x15\xaa\xc4\xafwdG\xc0\x9d\x89Q\x92\xc8k\xabF18\xb9!\x91\xf3\xba?{\x881r1T\x8dn"
}

Listing Event Signatures /api/v1/event-signatures/ GET

Returns a paginated list of event signatures.

{
  "next": "/api/v1/event-signatures/?page=2",
  "previous": null,
  "count": 100,
  "results": [
    {
      "id": 1,
      "created_at": "2020-09-13T18:45:58.559831Z",
      "text_signature": "RequestCreated(address,address,int256,uint256[12])",
      "hex_signature": "0x15aac4af776447c09d895192c86bab463c38b92191f3ba3f7b8831723c548d6e",
      "bytes_signature": "r'\x15\xaa\xc4\xafwdG\xc0\x9d\x89Q\x92\xc8k\xabF18\xb9!\x91\xf3\xba?{\x881r1T\x8dn"
    },
    ...
  ]
}

Response Status Codes

• 200 Success

Filtering Results

Filtering results are done similarly to filtering function Signature results

Creating Event Signatures /api/v1/event-signatures/ POST

Creates a new event signature

Example Request

{
  "text_signature": "MyEvent(address,uint)"
}

Response Status Codes

• 200 Success
• 400 Error

Example Success Response

On success, the serialized record will be returned

{
  "id": 1,
  "created_at": "2020-09-13T18:45:58.559831Z",
  "text_signature": "RequestCreated(address,address,int256,uint256[12])",
  "hex_signature": "0x15aac4af776447c09d895192c86bab463c38b92191f3ba3f7b8831723c548d6e",
  "bytes_signature": "r'\x15\xaa\xc4\xafwdG\xc0\x9d\x89Q\x92\xc8k\xabF18\xb9!\x91\xf3\xba?{\x881r1T\x8dn"
}

Accepted Formats for text_signature

Event signatures are normalized during creation. The normalization process can handle a wide array of input formats. Any of the following will normalize to transfer(address,uint256)

• event transfer(address _to, uint _value)
• event transfer(address _to, uint256 _value)
• transfer(address indexed _to, uint256 _value)
• transfer(address _to, uint _value)
• transfer(address, uint)
• transfer(address, uint256)
• transfer ( address, uint256 )
• transfer ( address indexed, uint256 ) anonymous

Example Error Response

When an error occurs, the response will be an object with keys mapping to arrays of error messages. A 400 response will be returned if the signature is already present, or if the format of the event signature could not be recognized.

{
  "text_signature": ["Unknown signature format"]
}

Retrieving Event Signatures /api/v1/event-signatures/:id/ GET

You can retrieve an individual event signature using this endpoint.

Response Status Codes

• 200 Success
• 404 Not Found

Example Success Response

On success, the serialized record will be returned

{
  "id": 1,
  "created_at": "2020-09-13T18:45:58.559831Z",
  "text_signature": "RequestCreated(address,address,int256,uint256[12])",
  "hex_signature": "0x15aac4af776447c09d895192c86bab463c38b92191f3ba3f7b8831723c548d6e",
  "bytes_signature": "r'\x15\xaa\xc4\xafwdG\xc0\x9d\x89Q\x92\xc8k\xabF18\xb9!\x91\xf3\xba?{\x881r1T\x8dn"
}