> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockscout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract

> ?module=contract

### `https://instance_base_url/api?module=contract`

## Get a list of contracts

`listcontracts`

List sorted in ascending order based on the time a contract was first indexed by the explorer. With filters \`unverified(2)\` the results will not be sorted for performance reasons.

**Example:**

```javascript theme={null}
https://instance_base_url/api
   ?module=contract
   &action=listcontracts
```

<Tabs>
  <Tab title="Request Param">
    | Parameter                      | Description                                                                                                                    |
    | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
    | page                           | optional nonnegative `integer` representing the page number used for pagination. 'offset' must also be provided.               |
    | offset                         | optional nonnegative `integer` representing the max number of records to return when paginating. 'page' must also be provided. |
    | filter                         | optional string `verified`\|`unverified`\|`empty`, or `1`\|`2`\|`3` respectively. Returns contracts with the requested status. |
    | verified\_at\_start\_timestamp | optional `unix timestamp` Represents the starting timestamp for verified contracts. Only used with `verified` filter.          |
    | verified\_at\_end\_timestamp   | optional `unix timestamp` Represents the ending timestamp for verified contracts. Only used with `verified` filter.            |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": [
        {
          "ABI": "[{\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event\"\n}, {\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event2\"\n}, {\n\"type\":\"function\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n\"name\":\"foo\",\n\"outputs\": []\n}]\n",
          "CompilerVersion": "v0.2.1-2016-01-30-91a6b35",
          "ContractName": "Test",
          "OptimizationUsed": "1",
          "SourceCode": "pragma solidity >0.4.24;\n\ncontract Test {\nconstructor() public { b = hex\"12345678901234567890123456789012\"; }\nevent Event(uint indexed a, bytes32 b);\nevent Event2(uint indexed a, bytes32 b);\nfunction foo(uint a) public { emit Event(a, b); }\nbytes32 b;\n}\n"
        }
      ],
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Get ABI for a verified contract

`getabi`

Also available through a GraphQL `addresses` query.

**Example:**

```javascript theme={null}
https://instance_base_url/api
   ?module=contract
   &action=getabi
   &address={addressHash}
```

<Tabs>
  <Tab title="Request Params">
    | Parameter   | Description                           |
    | ----------- | ------------------------------------- |
    | **address** | `string` containing the address hash. |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": "[{\"constant\":false,\"inputs\":[{\"name\":\"voucher_token\",\"type\":\"bytes32\"}],\"name\":\"burn\",\"outputs\":[{\"name\":\"success\",\"type\":\"bool\"}],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"constant\":true,\"inputs\":[{\"name\":\"voucher_token\",\"type\":\"bytes32\"}],\"name\":\"is_expired\",\"outputs\":[{\"name\":\"\",\"type\":\"bool\"}],\"payable\":false,\"stateMutability\":\"view\",\"type\":\"function\"},{\"constant\":false,\"inputs\":[{\"name\":\"voucher_token\",\"type\":\"bytes32\"}],\"name\":\"is_burnt\",\"outputs\":[{\"name\":\"\",\"type\":\"bool\"}],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"inputs\":[{\"name\":\"voucher_token\",\"type\":\"bytes32\"},{\"name\":\"_lifetime\",\"type\":\"uint256\"}],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"constructor\"}]",
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Get contract source code for a verified contract

`getsourcecode`

Also available through a GraphQL `addresses` query.

**Example:**

```javascript theme={null}
https://instance_base_url/api
   ?module=contract
   &action=getsourcecode
   &address={addressHash}
```

<Tabs>
  <Tab title="Request Param">
    | Parameter   | Description                           |
    | ----------- | ------------------------------------- |
    | **address** | `string` containing the address hash. |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": {
        "ABI": "[{\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event\"\n}, {\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event2\"\n}, {\n\"type\":\"function\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n\"name\":\"foo\",\n\"outputs\": []\n}]\n",
        "CompilerVersion": "v0.2.1-2016-01-30-91a6b35",
        "ContractName": "Test",
        "FileName": "{sourcify path or empty}",
        "ImplementationAddress": "0x000000000000000000000000000000000000000e",
        "IsProxy": "true",
        "OptimizationUsed": "1",
        "SourceCode": "pragma solidity >0.4.24;\n\ncontract Test {\nconstructor() public { b = hex\"12345678901234567890123456789012\"; }\nevent Event(uint indexed a, bytes32 b);\nevent Event2(uint indexed a, bytes32 b);\nfunction foo(uint a) public { emit Event(a, b); }\nbytes32 b;\n}\n"
      },
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Get contract creator address hash and creation transaction hash

`getcontractcreation`

Returns contract creator and transaction hash. Up to 10 contracts at the one request

**Example:**

```javascript theme={null}
https://instance_base_url/api
   ?module=contract
   &action=getcontractcreation
   &contractaddresses={addressHash},{addressHash}
```

<Tabs>
  <Tab title="Request Params">
    | Parameter             | Description                                          |
    | --------------------- | ---------------------------------------------------- |
    | **contractaddresses** | `string` containing address hashes, separated by `,` |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": [
        {
          "contractAddress": "0xdc2082945d55596bf39f362d9ec0f7f65edbb9dd",
          "contractCreator": "0xbb36c792b9b45aaf8b848a1392b0d6559202729e",
          "txHash": "0xe79426c9a5560cfbd78d0ef058e455c94483224ec265475583ff01ebdedceaf2"
        },
        {
          "contractAddress": "0x1b02da8cb0d097eb8d57a175b88c7d8b47997506",
          "contractCreator": "0xf87bc5535602077d340806d71f805ea9907a843d",
          "txHash": "0xe54bf38dfad760b8f96a76d8136d6540d74b02dafb5781746bf705bf7e647a3b"
        }
      ],
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Verify a contract with its source code and contract creation information

`verify`

**Example:**

```text theme={null}
https://instance_base_url/api
   ?module=contract
   &action=verify
   &addressHash={addressHash}
   &name={name}
   &compilerVersion={compilerVersion}
   &optimization={false}
   &contractSourceCode={contractSourceCode}
```

**Curl Post Example**

```sh theme={null}
curl -d '{"addressHash":"0xc63BB6555C90846afACaC08A0F0Aa5caFCB382a1","compilerVersion":"v0.5.4+commit.9549d8ff", "contractSourceCode":"pragma solidity ^0.5.4; contract Test { }","name":"Test","optimization":false}' -H "Content-Type: application/json" -X POST "https://blockscout.com/poa/sokol/api?module=contract&action=verify"
```

<Info>
  On successful submission you will receive a guid as a receipt. Use this with [`checkverifystatus`](/devs/apis/rpc/contract#return-status-of-a-verification-attempt)`to view verification status.`
</Info>

<Tabs>
  <Tab title="Params">
    | Parameter                      | Description                                                                   |
    | ------------------------------ | ----------------------------------------------------------------------------- |
    | **addressHash**                | `string` containing the address hash of the contract.                         |
    | **name**                       | `string` containing the name of the contract.                                 |
    | **compilerVersion**            | `string` containing the compiler version for the contract.                    |
    | **optimization**               | `enum` whether or not compiler optimizations were enabled `0`=false, `1`=true |
    | **contractSourceCode**         | `string` containing the source code of the contract.                          |
    | constructorArguments           | optional `string` constructor argument data provided.                         |
    | autodetectConstructorArguments | optional `boolean` whether or not automatically detect constructor argument.  |
    | evmVersion                     | optional EVM version for the contract.                                        |
    | optimizationRuns               | optional number of optimization runs used during compilation                  |
    | library1Name                   | optional `string` name of the first library used.                             |
    | library1Address                | optional `string` address of the first library used.                          |
    | library2Name                   | optional `string` name of the second library used.                            |
    | library2Address                | optional `string` address of the second library used.                         |
    | library3Name                   | optional `string` name of the third library used.                             |
    | library3Address                | optional `string` address of the third library used.                          |
    | library4Name                   | optional `string` name of the fourth library used.                            |
    | library4Address                | optional `string` address of the fourth library used.                         |
    | library5Name                   | optional `string` name of the fifth library used.                             |
    | library5Address                | optional `string` address of the fifth library used.                          |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": {
        "ABI": "[{\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event\"\n}, {\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event2\"\n}, {\n\"type\":\"function\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n\"name\":\"foo\",\n\"outputs\": []\n}]\n",
        "CompilerVersion": "v0.2.1-2016-01-30-91a6b35",
        "ContractName": "Test",
        "ImplementationAddress": "0x000000000000000000000000000000000000000e",
        "IsProxy": "true",
        "OptimizationUsed": "1",
        "SourceCode": "pragma solidity >0.4.24;\n\ncontract Test {\nconstructor() public { b = hex\"12345678901234567890123456789012\"; }\nevent Event(uint indexed a, bytes32 b);\nevent Event2(uint indexed a, bytes32 b);\nfunction foo(uint a) public { emit Event(a, b); }\nbytes32 b;\n}\n"
      },
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Verify a contract through [Sourcify](https://sourcify.dev/)

`verify_via_sourcify`

1. if a smart contract is already verified on Sourcify, it will automatically fetch the data from the [repo](https://repo.sourcify.dev/)

2. otherwise you need to upload source files and JSON metadata file(s).

**Example:**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=verify_via_sourcify
 &addressHash={addressHash}
```

#### POST body example

```text theme={null}
--6e1e4c11657c62dc1e4349d024de9e28
Content-Disposition: form-data; name="addressHash"

0xb77b7443e0F32F1FEBf0BE0fBd7124D135d0a525

--6e1e4c11657c62dc1e4349d024de9e28
Content-Disposition: form-data; name="files[0]"; filename="contract.sol"
Content-Type: application/json

...Source code...

--6e1e4c11657c62dc1e4349d024de9e28
Content-Disposition: form-data; name="files[1]"; filename="metadata.json"
Content-Type: application/json

...JSON metadata...

--6e1e4c11657c62dc1e4349d024de9e28--
```

<Tabs>
  <Tab title="Params">
    | Parameter       | Description                             |
    | --------------- | --------------------------------------- |
    | **addressHash** | `string` containing the address hash.   |
    | files           | `array` with sources and metadata files |
  </Tab>

  <Tab title="Example">
    ```json theme={null}
    {
      "message": "OK",
      "result": {
        "ABI": "[{\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event\"\n}, {\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event2\"\n}, {\n\"type\":\"function\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n\"name\":\"foo\",\n\"outputs\": []\n}]\n",
        "CompilerVersion": "v0.2.1-2016-01-30-91a6b35",
        "ContractName": "Test",
        "ImplementationAddress": "0x000000000000000000000000000000000000000e",
        "IsProxy": "true",
        "OptimizationUsed": "1",
        "SourceCode": "pragma solidity >0.4.24;\n\ncontract Test {\nconstructor() public { b = hex\"12345678901234567890123456789012\"; }\nevent Event(uint indexed a, bytes32 b);\nevent Event2(uint indexed a, bytes32 b);\nfunction foo(uint a) public { emit Event(a, b); }\nbytes32 b;\n}\n"
      },
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Verify a vyper contract with its source code and contract creation information

`verify_vyper_contract`

**Example**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=verify_vyper_contract
 &addressHash={addressHash}
 &name={name}
 &compilerVersion={compilerVersion}
 &contractSourceCode={contractSourceCode}
```

**curl POST example**

```powershell theme={null}
curl --location --request POST 'http://localhost:4000/api?module=contract&action=verify_vyper_contract' --form 'contractSourceCode="SOURCE_CODE"' --form 'name="Vyper_contract"' --form 'addressHash="0xE60B1B8bD493569a3E945be50A6c89d29a560Fa1"' --form 'compilerVersion="v0.2.12"'
```

<Tabs>
  <Tab title="First Tab">
    | Parameter              | Description                                                |
    | ---------------------- | ---------------------------------------------------------- |
    | **addressHash**        | `string` containing the address hash of the contract.      |
    | **name**               | `string` containing the name of the contract.              |
    | **compilerVersion**    | `string` containing the compiler version for the contract. |
    | **contractSourceCode** | `string` containing the source code of the contract.       |
    | constructorArguments   | `string` constructor argument data provided.               |
  </Tab>

  <Tab title="Example">
    ```json theme={null}
    {
      "message": "OK",
      "result": {
        "ABI": "[{\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event\"\n}, {\n\"type\":\"event\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\",\"indexed\":true},{\"name\":\"b\",\"type\":\"bytes32\",\"indexed\":false}],\n\"name\":\"Event2\"\n}, {\n\"type\":\"function\",\n\"inputs\": [{\"name\":\"a\",\"type\":\"uint256\"}],\n\"name\":\"foo\",\n\"outputs\": []\n}]\n",
        "CompilerVersion": "v0.2.1-2016-01-30-91a6b35",
        "ContractName": "Test",
        "ImplementationAddress": "0x000000000000000000000000000000000000000e",
        "IsProxy": "true",
        "OptimizationUsed": "1",
        "SourceCode": "pragma solidity >0.4.24;\n\ncontract Test {\nconstructor() public { b = hex\"12345678901234567890123456789012\"; }\nevent Event(uint indexed a, bytes32 b);\nevent Event2(uint indexed a, bytes32 b);\nfunction foo(uint a) public { emit Event(a, b); }\nbytes32 b;\n}\n"
      },
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Verify a contract with Standard input JSON file

`verifysourcecode`

**Example**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=verifysourcecode
 &codeformat={solidity-standard-json-input}
 &contractaddress={contractaddress}
 &contractname={contractname}
 &compilerversion={compilerversion}
 &sourceCode={sourceCode}
```

`solidity-single-file`:

```sh theme={null}
curl --location 'localhost:4000/api?module=contract&action=verifysourcecode' \
--form 'contractaddress="0xDc2082945d55596bf39F362d9EC0F7F65eDBB9DD"' \
--form 'sourceCode="// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.7.0 <0.9.0;

contract Storage {
    uint256 number;

    function store(uint256 num) public {
        number = num;
    }

    function retrieve() public view returns (uint256){
        return number;
    }
}"' \
--form 'contractname="Storage"' \
--form 'codeformat="solidity-single-file"' \
--form 'compilerversion="v0.8.17+commit.8df45f5f"' \
--form 'optimizationUsed="1"' \
--form 'runs="199"' \
--form 'constructorArguments=""' \
--form 'evmversion="london"' \
--form 'libraryname1="qwe"' \
--form 'libraryaddress1="0xDc2082945d55596bf39F362d9EC0F7F65eDBB9DD"'
--form 'licenseType=0'
```

<Tabs>
  <Tab title="Params">
    | Parameter                      | Description                                                                                                                                                                     |
    | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **codeformat**                 | Format of sourceCode (`solidity-standard-json-input` or `solidity-single-file`)                                                                                                 |
    | **contractaddress**            | `string` containing the address hash of the contract.                                                                                                                           |
    | **contractname**               | `string` name of the contract. It can be an empty string(""), just the contract name("ContractName"), or a filename and contract name("contracts/contract\_1.sol:ContractName") |
    | **compilerversion**            | `string` containing the compiler version for the contract.                                                                                                                      |
    | **sourceCode**                 | `string` standard input json or flattened solidity code                                                                                                                         |
    | optimizationUsed               | could be `0`, `false`, `1`, `true`. Should be set when `codeformat=solidity-single-file`                                                                                        |
    | runs                           | `integer` is equal to optimization runs number set on compilation. Should be set when `optimizationUsed` is `1` or `true`                                                       |
    | evmversion                     | `string` EVM version. Should be set when `codeformat=solidity-single-file`                                                                                                      |
    | constructorArguments           | optional `string` constructor argument data provided.                                                                                                                           |
    | autodetectConstructorArguments | optional `boolean` whether or not automatically detect constructor argument.                                                                                                    |
    | licenseType                    | `string` or `number` representing the license type.                                                                                                                             |

    **License type**

    "See [available license types](/devs/verification/blockscout-smart-contract-verification-api)."
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": "b080b96bd06ad1c9341c2afb7e3730311388544961acde94",
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Return status of a verification attempt

`checkverifystatus`

<Info>
  guid is received as a receipt from the `verifysourcecode` method.
</Info>

**Example**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=checkverifystatus
 &guid={identifierString}
```

<Tabs>
  <Tab title="Params">
    | Parameter | Description                                        |
    | --------- | -------------------------------------------------- |
    | **guid**  | `string` used for identifying verification attempt |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": "Pending in queue",
      "status": "1"
    }
    ```
  </Tab>
</Tabs>

<Info>
  Return Options: `Pending in queue` | `Pass - Verified` | `Fail - Unable to verify` | `Unknown UID`
</Info>

## Verify proxy contract

`verifyproxycontract`

**Example**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=verifyproxycontract
 &address={addressHash}
```

<Tabs>
  <Tab title="Params">
    | Parameter   | Description                                          |
    | ----------- | ---------------------------------------------------- |
    | **address** | `string` containing the address hash of the contract |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
        "message": "OK",
        "result": "c32d204404f33ff38fee42394f7e671fd96314b3658d466a",
        "status": "1"
    }
    ```
  </Tab>
</Tabs>

## Return status of a proxy contract verification attempt

`checkproxyverification`

<Info>
  guid is received as a receipt from the `verifyproxycontract` method.
</Info>

**Example**

```javascript theme={null}
https://instance_base_url/api
 ?module=contract
 &action=checkproxyverification
 &guid={identifierString}
```

<Tabs>
  <Tab title="Params">
    | Parameter | Description                                        |
    | --------- | -------------------------------------------------- |
    | **guid**  | `string` used for identifying verification attempt |
  </Tab>

  <Tab title="Example Result">
    ```json theme={null}
    {
      "message": "OK",
      "result": "Implementation (0x5a3f40fd57731bbf62a38fd290add074e9cdb844) was verified and saved for proxy (0xc32d204404f33ff38fee42394f7e671fd96314b3)",
      "status": "1"
    }
    ```

    <Info>
      Return Options:

      * `Verification in progress`

      * `The proxy's ({addressHash}) implementation contract is found at {addressHash} and is successfully updated.`

      * `A corresponding implementation contract was unfortunately not detected for the proxy address.`

      * `Unknown UID`
    </Info>
  </Tab>
</Tabs>