Ekubo Protocol

https://docs.ekubo.org/
Admin
Ekubo Protocol is an efficient AMM protocol that delivers the best pricing and capital-efficient...
Tokens:116,077
Snippets:626
Trust Score:7.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install @ekubo/yul-router-sdk

Source: https://docs.ekubo.org/integration-guides/sdks

Install the TypeScript SDK for encoding swap routes for EVM chains.

```bash
npm install @ekubo/yul-router-sdk
```

--------------------------------

### Install Yul Router SDK

Source: https://docs.ekubo.org/integration-guides/yul-router

Install the SDK package via npm.

```bash
npm install @ekubo/yul-router-sdk@0.8.0
```

--------------------------------

### Install @ekubo/sdk

Source: https://docs.ekubo.org/integration-guides/sdks

Install the TypeScript SDK for shared math and protocol encoding utilities.

```bash
npm install @ekubo/sdk
```

--------------------------------

### GET /

Source: https://docs.ekubo.org/openapi/quoter.json

Discover the quoter service and retrieve service metadata and canonical integration URLs.

```APIDOC
## GET /

### Description
Discover the quoter service and retrieve service metadata and canonical integration URLs.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- Service metadata and canonical integration URLs

#### Response Example
{
  "serviceMetadata": "object"
}

#### Error Response (404)
- Error response
```

--------------------------------

### GET /{chainId}/{amount}/{specifiedToken}/{otherToken}

Source: https://docs.ekubo.org/openapi/quoter.json

Get an exact-input or exact-output swap route quote. All amounts are base-unit decimal strings. For exact-input swaps, amount is positive, specifiedToken is the input token, and otherToken is the output token. For exact-output swaps, amount is negative, specifiedToken is the output token, and otherToken is the input token.

```APIDOC
## GET /{chainId}/{amount}/{specifiedToken}/{otherToken}

### Description
Get an exact-input or exact-output swap route quote. All amounts are base-unit decimal strings. For exact-input swaps, amount is positive, specifiedToken is the input token, and otherToken is the output token. For exact-output swaps, amount is negative, specifiedToken is the output token, and otherToken is the input token.

### Method
GET

### Endpoint
/{chainId}/{amount}/{specifiedToken}/{otherToken}

### Parameters
#### Path Parameters
- **chainId** (string) - Required - Chain ID
- **amount** (string) - Required - Positive exact-input amount or negative exact-output amount, denominated in specifiedToken. Pattern: ^-?[0-9]*[1-9][0-9]*$
- **specifiedToken** (string) - Required - Input token for exact input; output token for exact output
- **otherToken** (string) - Required - Output token for exact input; input token for exact output

### Request Example
For exact input:
{
  "amount": "100000000000000000",
  "specifiedToken": "0x0000000000000000000000000000000000000000",
  "otherToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

For exact output:
{
  "amount": "-100000000000000000",
  "specifiedToken": "0x0000000000000000000000000000000000000000",
  "otherToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

### Response
#### Success Response (200)
- A block-pinned executable split-route quote

#### Response Example
{
  "quote": "object"
}

#### Error Response (400)
- Error response

#### Error Response (403)
- Error response
```

--------------------------------

### GET /openapi.json

Source: https://docs.ekubo.org/openapi/quoter.json

Fetch the OpenAPI 3.1 document for the quoter service.

```APIDOC
## GET /openapi.json

### Description
Fetch the OpenAPI 3.1 document for the quoter service.

### Method
GET

### Endpoint
/openapi.json

### Response
#### Success Response (200)
- OpenAPI 3.1 document (object)

#### Response Example
{
  "openapi": "3.1.0"
}

#### Error Response (404)
- Error response
```

--------------------------------

### GET /campaigns

Source: https://docs.ekubo.org/openapi/ekubo.json

Lists all campaigns. Returns campaign details including start time, end time, next drop time, allowed extensions, and pairs.

```APIDOC
## GET /campaigns

### Description
Lists all campaigns. Returns campaign details including start time, end time, next drop time, allowed extensions, and pairs.

### Method
GET

### Endpoint
/campaigns

### Parameters
None

### Response
#### Success Response (200)
- **campaigns** (array) - Required - List of campaigns
  - **startTime** (string) - Start time of the campaign
  - **endTime** (string) - End time of the campaign
  - **nextDropTime** (string) - Next drop time
  - **allowedExtensions** (array) - Allowed file extensions
  - **pairs** (array) - Trading pairs

#### Response Example
{
  "campaigns": [
    {
      "startTime": "2023-01-01T00:00:00Z",
      "endTime": "2023-12-31T23:59:59Z",
      "nextDropTime": "2023-06-01T00:00:00Z",
      "allowedExtensions": ["jpg", "png"],
      "pairs": ["ETH/USDC"]
    }
  ]
}

#### Error Responses
- **400** - The request parameters are invalid
- **500** - An unexpected server error occurred
```

--------------------------------

### Run Indexer for Starknet or EVM

Source: https://docs.ekubo.org/products/indexer

Execute the indexer entrypoint for the desired chain family using the NETWORK environment variable to specify the network.

```bash
docker run --rm -e NETWORK=mainnet ekubo-indexer bun src/starknet.ts   # Starknet
docker run --rm -e NETWORK=mainnet ekubo-indexer bun src/evm.ts        # EVM chains
```

--------------------------------

### Starknet pool parameters URL

Source: https://docs.ekubo.org/integration-guides/reading-pool-price

Example URL showing how to identify pool parameters like fee and tick spacing for an ETH/USDC pool.

```text
https://ekubo.org/positions/new?baseCurrency=ETH&quoteCurrency=USDC&fee=170141183460469235273462165868118016&tickSpacing=1000
```

--------------------------------

### GET /tokens

Source: https://docs.ekubo.org/api

Get a list of tokens for the given chain ID. Supports search, pagination, and filtering by visibility priority.

```APIDOC
## GET /tokens

### Description
Get a list of tokens for the given chain ID.

### Method
GET

### Endpoint
/tokens

### Parameters
#### Query Parameters
- **chainId** (integer) - Required - The ID of the network that is being fetched. Format: int64, min: 1, max: 9223372036854776000.
- **search** (string) - Optional - Token symbol search. Min length: 1, max length: 32. Pattern: ^[^\u0000-\u001f\u007f-\u009f]*$
- **pageSize** (integer) - Optional - Integer numbers. Min: 1, max: 10000, default: 1000.
- **afterToken** (string) - Optional - The :-concatenated chain ID and token address for pagination. Pattern: ^(?:\d+|0x[a-fA-F0-9]+):0x[a-fA-F0-9]+$. Example: 1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.
- **minVisibilityPriority** (integer | null) - Optional - Token visibility priority threshold. Min: -100, max: 100, default: 0.
- **includePrices** (string enum) - Optional - Set to false to omit usd_price from every row. The price-free list only changes when token metadata does, so it is cached for longer; pair it with /tokens/prices to keep prices fresh. Values: true, false. Default: true.

### Request Example
```
curl https://prod-api.ekubo.org/tokens
```

### Response
#### Success Response (200)
List of tokens. Response schema:
```json
[
  {
    "chain_id": "string",
    "name": "string",
    "symbol": "string",
    "decimals": 0,
    "address": "string",
    "visibility_priority": 1,
    "sort_order": 1,
    "total_supply": null,
    "logo_url": "https://example.com",
    "usd_price": null,
    "bridgeInfos": null
  }
]
```

#### Error Responses
- **400** - The request parameters are invalid.
- **500** - An unexpected server error occurred.
```

--------------------------------

### IEkuboAutomation interface with automate(bytes) returning Call[]

Source: https://docs.ekubo.org/wallet/automations

Defines the single entry point a tick polls. The bytecode is installed at the wallet's address and invoked with the wallet as msg.sender; writes are discarded, so only the returned Call[] can reach the chain. A revert or an undecodable return value fails the tick.

```solidity
interface IEkuboAutomation {
    struct Call {
        address to;
        uint256 value;
        bytes data;
    }


    /// Runs as the wallet, at the wallet's address, inside a simulation whose
    /// writes are discarded. Deliberately not `view`: probe freely.
    function automate(bytes calldata config) external returns (Call[] memory);
}
```

--------------------------------

### GET /tokens

Source: https://docs.ekubo.org/openapi/ekubo.json

Get a list of tokens for the given chain ID. Supports optional search, pagination, and price inclusion parameters.

```APIDOC
## GET /tokens

### Description
Get a list of tokens for the given chain ID.

### Method
GET

### Endpoint
/tokens

### Parameters
#### Query Parameters
- **chainId** (integer) - Optional - The ID of the network that is being fetched. Minimum: 1, Maximum: 9223372036854776000.
- **search** (string) - Optional - Token symbol search. Min length: 1, Max length: 32.
- **pageSize** (integer) - Optional - Number of tokens per page. Default: 1000, Minimum: 1, Maximum: 10000.
- **afterToken** (string) - Optional - The :-concatenated chain ID and token address for pagination. Example: 1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.
- **minVisibilityPriority** (integer) - Optional - Token visibility priority threshold. Default: 0, Minimum: -100, Maximum: 100.
- **includePrices** (string) - Optional - Set to false to omit usd_price from every row. Default: "true".

### Response
#### Success Response (200)
- **chain_id** (string) - The chain ID of the token.
- **name** (string) - The name of the token.

#### Response Example
```json
{
  "chain_id": "1",
  "name": "USD Coin"
}
```
```

--------------------------------

### data: URI example for inline body

Source: https://docs.ekubo.org/wallet/producers

Shows a data: URI alternative that carries the body inline, removing the hosting requirement. Media type must be application/json; only ;base64 and charset= parameters are accepted. The reference is bounded by the same 16 MiB body cap.

```text
data:application/json;base64,eyJzY2hlbWFfdmVyc2lvbiI6IjEiLC…
```

--------------------------------

### Get position rewards via GET /rewards

Source: https://docs.ekubo.org/products/rewards

View the rewards earned by a specific position identified by locker and salt over a period.

```http
GET https://prod-api.ekubo.org/rewards/{chainId}/{locker}/{salt}
```

--------------------------------

### GET /price/{chainId}/{baseToken}/{quoteToken}/history

Source: https://docs.ekubo.org/openapi/ekubo.json

Get the VWAP-based price history for the given pair. This endpoint returns historical price data over a specified time range and interval.

```APIDOC
## GET /price/{chainId}/{baseToken}/{quoteToken}/history

### Description
Get the VWAP-based price history for the given pair.

### Method
GET

### Endpoint
/price/{chainId}/{baseToken}/{quoteToken}/history

### Parameters
#### Path Parameters
- **baseToken** (string) - Required - An address on the specified blockchain network. Can be a hexadecimal number (e.g., "0x0") or a decimal number.
- **quoteToken** (string) - Required - An address on the specified blockchain network. Can be a hexadecimal number (e.g., "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48") or a decimal number.
- **chainId** (string) - Required - A number represented in hexadecimal or decimal (e.g., "1").

#### Query Parameters
- **interval** (integer) - Optional - The interval in seconds between data points. Minimum is 60, default is 1800.
- **start** (integer) - Optional - Unix timestamp (seconds) of the start of the range; defaults to 60 intervals before end.

### Response
#### Success Response (200)
- **timestamp** (integer) - The timestamp of the data point.
- **start** (integer) - The start of the time range.
- **end** (integer) - The end of the time range.
- **interval** (integer) - The interval between data points.
- **data** (array) - Array of data points, each containing:
  - **start** (number) - The start time of the data point.
  - **price** (number) - The VWAP price for the interval. Must be greater than 0.

#### Response Example
{
  "timestamp": 1700000000,
  "start": 1700000000,
  "end": 1700003600,
  "interval": 1800,
  "data": [
    {
      "start": 1700000000,
      "price": 1.234
    }
  ]
}

#### Error Responses
- **400** - The request parameters are invalid.
- **404** - The requested resource was not found.
- **500** - An unexpected server error occurred.

Error responses use the ErrorResponse schema.
```

--------------------------------

### Example Ekubo locker contract implementing ILocksCoreExample

Source: https://docs.ekubo.org/integration-guides/aggregators

Shows a Cairo contract that implements the ILocker pattern. It serializes SwapData, calls ICore#lock, and in the locked callback verifies the caller is the Ekubo core contract, deserializes the swap data, and performs swaps. Comments illustrate how to handle deltas with withdraw, transfer, and deposit.

```Cairo
// ILocksCoreExample interface and imports are implied here


#[starknet::contract]
mod Example {
  #[storage]
  struct Storage {
    ekubo: ContractAddress,
  }


  #[derive(Copy, Drop, Serde)]
  struct SwapData {
     // the list of pools that you'd like to swap against, etc.
  }


  #[derive(Copy, Drop, Serde)]
  struct SwapResult {
     // the result of the swap
  }


  #[external(v0)]
  impl LocksCoreExample of ILocksCoreExample<ContractState> {
    fn swap(ref self: ContractState, swap_data: SwapData) -> SwapResult {
      let mut arr: Array<felt252> = ArrayTrait::new();
      Serde::<SwapData>::serialize(@swap_data, ref arr);


      let result = ICoreDispatcher { contract_address: self.ekubo.read() }.lock(arr);


      let mut result_data = result.span();
      let mut result: SwapResult = Serde::<SwapResult>::deserialize(
          ref result_data
      )
          .expect('DESERIALIZE_RESULT_FAILED');


      result
    }


    fn locked(ref self: ContractState, id: u32, data: Array<felt252>) -> Array<felt252> {
      let caller = get_caller_address();
      let ekubo = self.ekubo.read();
      // Only allow Ekubo's core contract to call this method.
      assert(caller == ekubo, 'UNAUTHORIZED_CALLBACK');


      let mut swap_data_span = data.span();
      let mut swap_data: SwapData = Serde::<SwapData>::deserialize(ref swap_data_span)
          .expect('DESERIALIZE_FAILED');


      // Do your swaps here! e.g.:
      // let delta = ICoreDispatcher { contract_address: ekubo }.swap(pool_key, params);


      // Each swap generates a "delta", but does not trigger any token transfers.
      // A negative delta indicates you are owed tokens. A positive delta indicates core owes you tokens.
      // To take a negative delta out of core, do (assuming token0):
      // ICoreDispatcher { contract_address: ekubo }.withdraw(token, recipient, delta.amount0.mag);
      // To pay tokens you owe, do (assuming token1):
      // IERC20Dispatcher {
      //   contract_address: token
      // }.transfer(ekubo, u256 { low: delta.mag, high: 0 });
      // assert(
      //   ICoreDispatcher { contract_address: ekubo }.deposit(token) == delta.amount1.mag,
      //   'DEPOSIT_FAILED'
      // );




      let mut arr: Array<felt252> = ArrayTrait::new();
      Serde::<SwapResult>::serialize(@result, ref arr);
      arr
    }
  }
}
```

--------------------------------

### Execution plan reference envelope example

Source: https://docs.ekubo.org/wallet/producers

Shows the JSON envelope that preparation tools return under the key execution_plan_reference. The wallet passes this object unchanged as its reference argument. The integrity object is parsed strictly with no extra fields, and bytes must match the exact byte length of the stored body.

```json
{
  "kind": "artifact_reference",
  "artifact_type": "execution_plan",
  "url": "https://plans.example.com/artifact/0f8c2b1e-…",
  "integrity": {
    "algorithm": "keccak256",
    "value": "0x5bec7df0e57e9f5c55461eb450a7aa567a42403f4b32ea55df8e5cff346e1ba5"
  },
  "bytes": 1632,
  "instruction": "Pass this reference object unchanged as the wallet's reference argument."
}
```

--------------------------------

### GET /governance/{chainId}/proposals

Source: https://docs.ekubo.org/openapi/ekubo.json

Returns the list of all proposals.

```APIDOC
## GET /governance/{chainId}/proposals

### Description
Returns the list of all proposals.

### Method
GET

### Endpoint
/governance/{chainId}/proposals

### Parameters
#### Path Parameters
- **chainId** (string) - Required - Chain ID for which to list proposals. Accepts hexadecimal (^0x[a-fA-F0-9]+$) or decimal (^\d+$) numbers.

### Response
#### Success Response (200)
Returns the list of all proposals.

#### Error Responses
- **400** - The request parameters are invalid.
- **404** - The requested resource was not found.
- **500** - An unexpected server error occurred.
```

--------------------------------

### read_calls artifact JSON example

Source: https://docs.ekubo.org/wallet/producers

Example of a read_calls artifact body. The body is the wallet's batch-read argument object exactly, with nothing added. Unknown fields are rejected. The decode plan is optional; keep include_raw true because raw return bytes are authoritative.

```json
{
  "chain_id": "1",
  "block_parameter": "latest",
  "calls": [
    {
      "id": "usdc_balance",
      "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "data": "0x70a08231000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266",
      "decode": {
        "kind": "function_result",
        "abi": [
          {
            "type": "function",
            "name": "balanceOf",
            "stateMutability": "view",
            "inputs": [{ "name": "account", "type": "address" }],
            "outputs": [{ "name": "", "type": "uint256" }]
          }
        ],
        "function_name": "balanceOf",
        "required": true
      },
      "include_raw": true
    }
  ]
}
```

--------------------------------

### List campaigns via GET /campaigns

Source: https://docs.ekubo.org/products/rewards

Retrieve a list of active liquidity incentive campaigns for a specific chain.

```http
GET https://prod-api.ekubo.org/campaigns?chainId={chainId}
```
Tokens:
Raw