# API

At the moment, only one endpoint is available, if there is some data that you'd like to fetch from the API, please reach out to <antoine@tryethernal.com>, @antoinedc on Discord or @adechevigne on Twitter!

## Authentication

To authenticate, you'll need an auth token that you will find on the "Settings" page. The "API" integration needs to be enabled for requests to go through.

Once you've enabled the integration, the token will be displayed below.

Pass it in a `token` GET parameter to the endpoint you'd like to use.

{% hint style="warning" %}
Each workspace has its own token
{% endhint %}

## Endpoints

## Storage

<mark style="color:blue;">`GET`</mark> `https://api.tryethernal.com/contracts/:contractAddress/storage?token=xxx&paths[]=["balances", "0x123456789"]`

Reads values of the variables of the contract at address `contractAddress`. This makes available data you'll find in the "Storage" tab in contracts pages through an API.\
\
You need to pass an array of arrays, where each element is the path to the variable you want to read.\
Top level primitives are automatically decoded, you don't need to specify them in the path.\
If a variable is not found, an error will be returned.\
\
Example:\
If we have a contract with the following variables declared:\
`(address => uint256) balances;`\
`uint256 total;`\
\
And if we want to read the total and the balance for addresses `0x1234` and `0x5678`, we would call the following:\
`https://api.tryethernal.com/contracts/0xabcdef/storage?token=xxx&paths[]=["balances", "0x1234"]&paths[]=["balances", "0x5678"]`\
\
`total` will always be returned.\
\
The response will have two fields: a paths field that returns asked paths, and a storage field that will contains the values.\
In this case, it would be:\
`{`\
&#x20;   `paths: [`\
&#x20;      `['balances', '0x1234'],`\
&#x20;      `['balances', '0x5678']`\
&#x20;   `],`\
&#x20;   `storage: {`\
&#x20;       `balances: {`\
&#x20;           `'Ox1234': '10000',`\
&#x20;           `'0x5678': '20000'`\
&#x20;       `},`\
&#x20;       `total: '30000'`\
&#x20;   `}`\
`}`\
\
You can find more details about variable reading in this section.

#### Path Parameters

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| contractAddress | string | Address of the contract |

#### Query Parameters

| Name  | Type   | Description                             |
| ----- | ------ | --------------------------------------- |
| paths | array  | Paths of the variables you want to read |
| token | string | Authentication token                    |

{% tabs %}
{% tab title="200 Returns queried path and variables values." %}

```
{
    paths: [
       ['balances', '0x1234'],
       ['balances', '0x5678']
    ],
    storage: {
        balances: {
            'Ox1234': '10000',
            '0x5678': '20000'
        },
        total: '30000'
    }
}
```

{% endtab %}

{% tab title="400 Can return one of the following:" %}

```
{ message: 'API integration for workspace Hardhat is disabled' }
{ message: 'No contract at 0xabcd in workspace Hardhat' }
{ message: 'API integration for workspace Hardhat is disabled' }
{ message: 'No artifact for contract at 0xabcd in Hardhat' }
{ message: 'No such variable balance' }
```

{% endtab %}

{% tab title="401 Can return one of the following" %}

```
{ message: 'Failed authentication' }
{ message: 'Missing auth token' }
```

{% endtab %}
{% endtabs %}