# Usage

This section explains how to integrate and use the **Tycho-Orderbook** crate in your project.

### 1. Adding the Dependency

You can clone the repository and point the SDK dependency to the locally forked SDK.

The SDK is not yet published on [crates.io](https://crates.io/).

```
git clone https://github.com/0xMerso/tycho-orderbook-sdk sdk
```

In the `Cargo.toml` of your project.

```toml
[dependencies]
tycho-orderbook = { path = "../sdk" } 
```

For a complete code example, please go directly to [Quickstart](/docs/rust-sdk/quickstart.md).

### 2. Instantiate the provider and build an orderbook

The OrderbookBuilder structure is used to build an OrderbookProvider, which creates a stream of data and events for the specified network.

The builder requires a Tycho *ProtocolStreamBuilder* takes into account numerous configuration parameters, such as supported exchanges (Uniswap, Curve, etc.) and pool filters (minimum TVL).

```rust
let network = networks.clone().into_iter().find(|x| x.name == name).expect("Network not found");
let mut psb = ProtocolStreamBuilder::new(&network.tycho, chain)
        .exchange::<UniswapV2State>(TychoSupportedProtocol::UniswapV2.to_string().as_str(), filter.clone(), None)
        .exchange::<UniswapV3State>(TychoSupportedProtocol::UniswapV3.to_string().as_str(), filter.clone(), None)
        .exchange::<UniswapV4State>(TychoSupportedProtocol::UniswapV4.to_string().as_str(), filter.clone(), Some(u4))
        .auth_key(Some(key.clone()))
        .skip_state_decode_failures(true)
        .set_tokens(tokens.clone())
        .await;

let builder = OrderbookBuilder::new(network.clone(), psb, key.clone(), tokens.clone());
match builder.build(xstate).await {
         Ok(provider: OrderbookProvider) => {
                 [..]
         }
}


```

The OrderbookProvider structure is the crate's main component. It listens to Tycho streams, and opens a stream on which the client will listen for new events.\
Each time a new event is emitted, you'll know which states have changed, i.e. liquidity pools that have executed swaps.

The OrderbookProvider has a shared memory state which is used to internally update data that includes liquidity pool (= component) data. More importantly, this Arc Mutex structure contains pointers to the simulation functions provided by Tycho for each component, used to compute the orderbooks.

```rust

if let Some(event) = stream.recv().await {
    [...]
    OrderbookEvent::NewHeader(block, updated) => {
        // You are notified by the stream when liquidity pool state change
    }
}
```

You can now trigger the recalculation of the orderbook.

```rust
provider.get_orderbook(DefaultOrderbookSolver,
    OrderbookRequestParams { tag: key.clone(), point: None }
).await
```

The solver is used here to find the optimal path for a given trade (for example, how much to allocate for 100 ETH on 5 ETH-USDC pools).

The orderbook returned is as follow.

```rust
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct Orderbook {
    [...]
    pub base: SrzToken,
    /// Token1. Output then output token
    pub quote: SrzToken,
    /// Array of resulat for the optimal single hop route
    pub bids: Vec<TradeResult>,
    /// Array of resulat for the optimal single hop route
    pub asks: Vec<TradeResult>,
    /// All components used to build the orderbook (= pools that include both token0 and token1)
    pub pools: Vec<SrzProtocolComponent>,
    [...]
}
```

An orderbook is characterized by a tag, which is the address of base token, a dash '-', and the address of the quote token. For instance, for BTC-USDC on ethereum, BTC is the base token.

```
0x2260fac5e5542a773aa44fbcfedf7c193bc2c599-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
```

The base token is the first token, the quote is the second, in the same order as when you request an orderbook with the 0xTokenBase-0xTokenQuote tag.

To create an orderbook and obtain its formalised bids/asks, using OrderbookProvider, you need to do:

```
obp.get_orderbook(OrderbookRequestParams { tag: tag.clone(), point: None }, Some(simufns)).await
let depth = book.depth(None);   
```

The point structure for SinglePointSimulation can be filled in to simulate a single trade, i.e a given degree of depth in the orderbook in fact.

### 3. Execution

You can execute any transaction using the SDK, which will build the transaction to be executed on Tycho Router contract, and approve it beforehand with Permit2.

You will find more information on the Tycho documentation [here](https://docs.propellerheads.xyz/tycho/for-solvers/execution/executing).

```rust

let request = ExecutionRequest {
    sender: sender.to_string().clone(),
    tag: book.tag.clone(),
    input: book.base.clone(),
    output: book.quote.clone(),
    amount,
    expected,
    distribution: way.distribution.clone(),
    components: book.pools.clone(),
};

// Build transactions
match book.create(network.clone(), request, originals.clone(), pk.clone()).await {
    Ok(payload) => {
        // Broadcast
        match book.send(network.clone(), payload, pk.clone()).await {}
    }
}
```

For a complete code example, please go directly to [Quickstart](/docs/rust-sdk/quickstart.md).


---

# 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://tycho-orderbook.gitbook.io/docs/rust-sdk/usage.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.