# GET

## Get Markets

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/markets?status=s&depth=d`

This endpoint allows you to request a list of markets.

#### Query Parameters

| Name   | Type    | Description                      |
| ------ | ------- | -------------------------------- |
| status | string  | **active** or **matured**        |
| depth  | integer | The number of markets to return. |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "underlying": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "maturity": "1648177200"
  }
]
```

{% endtab %}
{% endtabs %}

## Get Orderbook

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/orderbook?underlying=u&maturity=m`

This endpoint allows you to request an orderbook of a given depth for a specified market.\
\
Returns receiving premium and paying premium orders in descending/ascending order including *availableVolume* translated into both *premiumAvailable* and *principalAvailable*.

#### Query Parameters

| Name                                         | Type    | Description                                                   |
| -------------------------------------------- | ------- | ------------------------------------------------------------- |
| underlying<mark style="color:red;">\*</mark> | string  | The underlying token being transacted. E.g. USDC, DAI, etc.,  |
| maturity<mark style="color:red;">\*</mark>   | string  | The maturity of market in unix seconds.                       |
| depth                                        | integer | The number of orders on each side of the orderbook to return. |

{% tabs %}
{% tab title="200 " %}

```
{
    "receivingPremium": [
        {
            "order": {
                "key": "0xae3f59eabffcf1f15f384d5e582985d31a9aef4b181ecf56a0a37bab85013f1f",
                "maker": "0x335c0552eb130f3Dfbe6efcB4D2895aED1E9938b",
                "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
                "vault": false,
                "exit": false,
                "principal": "10000000000000000000000",
                "premium": "799000000000000000000",
                "maturity": "1669957199",
                "expiry": "1641386982"
            },
            "meta": {
                "price": "0.0799",
                "signature": "0x94836bc0b91695430e738f53e08cfef34ee1c048c42f9d846732cd867bf5376233ed86fb6b324dd9fac98c3e53c8e7f00b9c5c80fbd2d00bf8c5a177fbe8d38f1b",
                "premiumAvailable": "799000000000000000000",
                "principalAvailable": "10000000000000000000000",
                "sequence": 69218
            }
        }
    ],
    "payingPremium": [
        {
            "order": {
                "key": "0xa8181ff6e0bfa16130944d5add7220eed46f44796de7d4216728dde40376ac5e",
                "maker": "0x096Da21Ac79ae1EDbC69A07CE5c705E6c77Fec90",
                "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
                "vault": true,
                "exit": false,
                "principal": "107758620689655172413793",
                "premium": "10000000000000000000000",
                "maturity": "1669957199",
                "expiry": "1641371984"
            },
            "meta": {
                "price": "0.0928",
                "signature": "0xa4e8958193cf2cb9c70e4c4a7df9c3c7b68f89fd2f250d80e6bc9dbd9cba8c54415fb2f4d8da33c1d81d5a028233255b52adbf36bee3a2a929fb3ea3e735ff7a1c",
                "premiumAvailable": "10000000000000000000000",
                "principalAvailable": "107758620689655172413793",
                "sequence": 63593
            }
        }
    ],
    "timestamp": 1640178800,
    "nonce": 69218
}
```

{% endtab %}
{% endtabs %}

## Get Order

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/orders/key`

This endpoint allows you to request the detailed state and parameters for a given order.

Returns the orders parameters as well as order price, volume available and initial timestamp.

#### Path Parameters

| Name                                  | Type   | Description |
| ------------------------------------- | ------ | ----------- |
| key<mark style="color:red;">\*</mark> | String | Order key   |

{% tabs %}
{% tab title="200 " %}

```
{
    "order": {
        "key": "0xae3f59eabffcf1f15f384d5e582985d31a9aef4b181ecf56a0a37bab85013f1f",
        "maker": "0x335c0552eb130f3Dfbe6efcB4D2895aED1E9938b",
        "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
        "vault": false,
        "exit": false,
        "principal": "10000000000000000000000",
        "premium": "799000000000000000000",
        "maturity": "1669957199",
        "expiry": "1641386982"
    },
    "meta": {
        "price": "0.0799",
        "signature": "0x94836bc0b91695430e738f53e08cfef34ee1c048c42f9d846732cd867bf5376233ed86fb6b324dd9fac98c3e53c8e7f00b9c5c80fbd2d00bf8c5a177fbe8d38f1b",
        "premiumAvailable": "799000000000000000000",
        "principalAvailable": "10000000000000000000000",
        "sequence": 69218
    }
}
```

{% endtab %}
{% endtabs %}

## Get Effective Price (Preview Market Order)

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/fillpreview?underlying=u&maturity=m&volume=v&vault=w&exit=e`

This endpoint allows you to request a limit order payload that matches a given market order.\
\
Returns the effective price as well as orders for consumption.

#### Query Parameters

| Name                                         | Type    | Description                                                                       |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| underlying<mark style="color:red;">\*</mark> | string  | The underlying token being transacted. E.g. USDC, DAI, etc.,                      |
| maturity<mark style="color:red;">\*</mark>   | string  | The duration of the rolling-maturity market in seconds. E.g. 31536000 (12 months) |
| volume<mark style="color:red;">\*</mark>     | string  | The amount of currency to use.                                                    |
| vault<mark style="color:red;">\*</mark>      | boolean | Indicates if an order is in relation to a initiating/exiting a vault or zcToken   |
| exit<mark style="color:red;">\*</mark>       | boolean | Indicated if an order is an exit or an initiate                                   |

{% tabs %}
{% tab title="200 " %}

```
{
    "orders": [
        {
            "order": {
                "key": "0xa8181ff6e0bfa16130944d5add7220eed46f44796de7d4216728dde40376ac5e",
                "maker": "0x096Da21Ac79ae1EDbC69A07CE5c705E6c77Fec90",
                "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
                "vault": true,
                "exit": false,
                "principal": "107758620689655172413793",
                "premium": "10000000000000000000000",
                "maturity": "1669957199",
                "expiry": "1641371984"
            },
            "meta": {
                "price": "0.0928",
                "signature": "0xa4e8958193cf2cb9c70e4c4a7df9c3c7b68f89fd2f250d80e6bc9dbd9cba8c54415fb2f4d8da33c1d81d5a028233255b52adbf36bee3a2a929fb3ea3e735ff7a1c",
                "premiumAvailable": "10000000000000000000000",
                "principalAvailable": "107758620689655172413793",
                "previewFill": "1000",
                "sequence": 63593
            }
        }
    ],
    "effectivePrice": "0.092799999999999997156",
    "timestamp": 1640178873
}
```

{% endtab %}

{% tab title="400 Passed volume exceeds available" %}

```
{
     "message": "passed volume exceeds available" 
}
```

{% endtab %}

{% tab title="400: Bad Request Passed volume exceeds the maximum number of orders allowed" %}

```javascript
{
    "error" {
        "message": "passed volume exceeds the maximum number of orders allowed"
    }
}
```

{% endtab %}
{% endtabs %}

## Get Order History

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/users/:address/orders?underlying=u&maturity=m&status=s`

This endpoint allows you to request the order history for a given address, and allows filtering by **active**, **cancelled**, **full** and **expired** statuses.\
\
Returns chronologically sorted orders for a given address.

#### Query Parameters

| Name                                         | Type         | Description                                                             |
| -------------------------------------------- | ------------ | ----------------------------------------------------------------------- |
| address<mark style="color:red;">\*</mark>    | string       | Public key of an order's creator                                        |
| underlying<mark style="color:red;">\*</mark> | string       | The underlying token being transacted. E.g. USDC, DAI, etc.,            |
| maturity<mark style="color:red;">\*</mark>   | string       | The maturity of market in unix seconds.                                 |
| status                                       | list(string) | List of statuses **expired**, **cancelled**, **full** or **insolvent**. |

{% tabs %}
{% tab title="200 " %}

```
{
    "orders": [
        {
            "order": {
                "key": "0x279eb2584cb32ccc7a512d3d46e3dbb83ecde4b0c231c3f4838cae0ea70223e8",
                "maker": "0x096Da21Ac79ae1EDbC69A07CE5c705E6c77Fec90",
                "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
                "vault": false,
                "exit": false,
                "principal": "30000000000000000000000",
                "premium": "3333000000000000000000",
                "maturity": "1669957199",
                "expiry": "1641372040"
            },
            "meta": {
                "price": "0.1111",
                "signature": "0x75d626fdf62c67cf1de04f077fd7447f1164976f7f60826a63eece886923c11b59f061bd7b6d81fa96cdc3208ff53d4926ad8ba66d06a9101cc81d0e23792aaa1c",
                "premiumAvailable": "3333000000000000000000",
                "principalAvailable": "30000000000000000000000",
                "sequence": 63604
            }
        },
        {
            "order": {
                "key": "0xa8181ff6e0bfa16130944d5add7220eed46f44796de7d4216728dde40376ac5e",
                "maker": "0x096Da21Ac79ae1EDbC69A07CE5c705E6c77Fec90",
                "underlying": "0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa",
                "vault": true,
                "exit": false,
                "principal": "107758620689655172413793",
                "premium": "10000000000000000000000",
                "maturity": "1669957199",
                "expiry": "1641371984"
            },
            "meta": {
                "price": "0.0928",
                "signature": "0xa4e8958193cf2cb9c70e4c4a7df9c3c7b68f89fd2f250d80e6bc9dbd9cba8c54415fb2f4d8da33c1d81d5a028233255b52adbf36bee3a2a929fb3ea3e735ff7a1c",
                "premiumAvailable": "10000000000000000000000",
                "principalAvailable": "107758620689655172413793",
                "sequence": 63593
            }
        },
    ...
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request E.g. Invalid maturity" %}

```javascript
{
    "error": {
        "message": "invalid maturity"
    }
}
```

{% endtab %}
{% endtabs %}

## Get Last Trade Info

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/fills?underlying=u&maturity=m&depth=d`

This endpoint allows you to request the agreement most recently initiated in a given market. (The trade last made in a given market)\
\
Returns the parameters of the most recent agreement for the specified market.

#### Query Parameters

| Name                                         | Type   | Description                                                                                                           |
| -------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| underlying<mark style="color:red;">\*</mark> | string | The underlying token being transacted. E.g. USDC, DAI, etc.,                                                          |
| maturity<mark style="color:red;">\*</mark>   | string | The maturity of market in unix seconds.                                                                               |
| depth<mark style="color:red;">\*</mark>      | string | Should always be **1** to return one last trade. If more specified, the result will be a sorted  list of last trades. |

{% tabs %}
{% tab title="200 " %}

```
[
    {
        "key": "0xae3f59eabffcf1f15f384d5e582985d31a9aef4b181ecf56a0a37bab85013f1f",
        "price": "0.0799",
        "exit": false,
        "vault": false,
        "volume": "1.251564456e+20"
    }
]
```

{% endtab %}

{% tab title="400: Bad Request E.g. Invalid maturity" %}

```javascript
{
    "error": {
        "message": "invalid maturity"
    }
}
```

{% endtab %}
{% endtabs %}

## Get OHCLV

<mark style="color:blue;">`GET`</mark> `https://api.swivel.exchange/v2/samples?underlying=x&maturity=y&start=z&end=e&interval=f&type=g`

This endpoint allows you to request OHLCV points for the given period.\
\
Returns OHLCV points with each containing its OHLCV data at the given timestamp.

#### Query Parameters

| Name                                         | Type   | Description                                                                    |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| interval<mark style="color:red;">\*</mark>   | string | The time between datapoints in minutes dividable by 5. E.g. 5, 15, 30, 60, ... |
| maturity<mark style="color:red;">\*</mark>   | string | The maturity of market in unix seconds.                                        |
| underlying<mark style="color:red;">\*</mark> | string | The underlying token contract being transacted. E.g. USDC, DAI, etc.,          |
| start<mark style="color:red;">\*</mark>      | number | Start of of the period in seconds                                              |
| end<mark style="color:red;">\*</mark>        | number | End of the period in seconds                                                   |
| type<mark style="color:red;">\*</mark>       | string | Sampling type e.g. OHLCV                                                       |

{% tabs %}
{% tab title="200 " %}

```
[
    {
        "timestamp": 1638472500,
        "data": {
            "open": "0.0499",
            "high": "0.0499",
            "low": "0.0499",
            "close": "0.0499",
            "volume": "252275019238957087498"
        }
    },
    {
        "timestamp": 1638473400,
        "data": {
            "open": "0.0499",
            "high": "0.05",
            "low": "0.0499",
            "close": "0.05",
            "volume": "170000000000000000000"
        }
    },
...
]
```

{% endtab %}

{% tab title="400: Bad Request E.g. Invalid maturity" %}

```javascript
{
    "error": {
        "message": "invalid maturity"
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swivel.finance/swivel-v2.0.0/developers/exchange/get.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.