> For the complete documentation index, see [llms.txt](https://docs.mangrove.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mangrove.exchange/dev/protocol/technical-references/the-order-book/offer-views.md).

# Offer Views

Mangrove exposes a range of getter functions to query offer lists and offers directly on-chain or via helper contracts.

#### Getting the Best Offer

```
uint best = mgv.best(olKey);
```

Returns the ID of the best available offer (highest bid or lowest ask, depending on the side).

Solidity

```solidity
import {IMangrove} from "@mgv/src/IMangrove.sol";
// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv));

// OLKey olkey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olkey = OLKey(address(base), address(quote), 1);

uint best = mgv.best(olkey);
```

**Getting Offer Data**

| Function                              | Description                                    |
| ------------------------------------- | ---------------------------------------------- |
| `offers(olKey, offerId)`              | Returns packed offer data                      |
| `offerDetails(olKey, offerId)`        | Returns packed offer detail data               |
| `offerData(olKey, offerId)`           | Returns both offer and detail in packed format |
| `MgvReader.offerInfo(olKey, offerId)` | Returns unpacked structs for off-chain use     |

> The data pertaining to a particular offer is contained in the `OfferUnpacked` and `OfferDetailUnpacked` structs, which are stored as packed custom types called, respectively, `OfferPacked` and `OfferDetailPacked`. For on-chain calls, Mangrove provides unpacking functions to extract a particular field out of a packed structure. For off-chain calls, Mangrove also provide direct getters for the unpacked structures.

Solidity

```solidity
import {IMangrove} from "@mgv/src/IMangrove.sol";
import {MgvReader} from "@mgv/src/periphery/MgvReader.sol";
import "@mgv/src/core/MgvLib.sol";

// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mangroveAddress));

// MgvReader reader = MgvReader(<address of MgvReader>);
MgvReader reader = MgvReader(readerAddress);

// OLKey olKey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olKey = OLKey(address(base), address(quote), 1);

// Tick tick = TickLib.tickFromVolumes(<inbound amount>, <outbound amount>);
// ratio = <inbound amount> / <outbound amount>
Tick tick = TickLib.tickFromVolumes(5, 4);  // ratio = 5/4 = 1.25

// creates an offer at `tick` and store its ID in ofrId
// newOfferByTick(<offer list key>, <tick>, <gives>, <gasreq>, <gasprice>)
uint ofrId = mgv.newOfferByTick(olKey, tick, 1 ether, 10_000, 20);

// getting packed offer data
Offer offer = mgv.offers(olKey, ofrId);
OfferDetail detail = mgv.offerDetails(olKey, ofrId);
(offer, detail) = mgv.offerData(olKey, ofrId);

// for all fields f of OfferUnpacked
// offer.f == offer32.f()
// for all fields f of OfferDetailUnpacked
// offerDetail.f == offerDetail32.f()

// getting unpacked offer data
// MgvReader.offerInfo(<offer list key>, <offer ID>);
(OfferUnpacked memory offer, OfferDetailUnpacked memory offerDetail) =
  reader.offerInfo(olKey, offerId);
```

#### **Checking Offer Liveness**

An offer is *live* if it can be matched by a taker (i.e., `gives > 0`).

```solidity
bool isLive = mgv.offers(olKey, offerId).isLive();
```

Solidity

```solidity
import {IMangrove} from "@mgv/src/IMangrove.sol";

// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv));

// OLKey olkey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olKey = OLKey(address(base), address(quote), 1);

// Tick tick = TickLib.tickFromVolumes(<inbound amount>, <outbound amount>);
// ratio = <inbound amount> / <outbound amount>
Tick tick = TickLib.tickFromVolumes(5, 4);  // ratio = 5/4 = 1.25

// creates an offer at `tick` and store its ID in ofrId
// newOfferByTick(<offer list key>, <tick>, <gives>, <gasreq>, <gasprice>)
uint ofrId = mgv.newOfferByTick(olKey, tick, 1 ether, 10_000, 20);

// checking whether the offer is live in the offer list
bool isLive = mgv.offers(olKey, ofrId).isLive();
```

#### Custom types

Offer data is split between `OfferUnpacked` and `OfferDetailUnpacked` for storage read/write optimization (as both structs can be efficiently packed in storage).

### `OfferUnpacked`

| Field   | Type   | Comments                                                            |
| ------- | ------ | ------------------------------------------------------------------- |
| `prev`  | `uint` | ID of the preceding offer with the same tick (if the offer is live) |
| `next`  | `uint` | ID of the next offer with the same tick (if the offer is live)      |
| `tick`  | `Tick` | The offer's "price" tick                                            |
| `gives` | `uint` | The amount of outbound token the offer gives                        |

### `OfferDetailUnpacked`

| Field                | Type      | Comments                                                                           |
| -------------------- | --------- | ---------------------------------------------------------------------------------- |
| `maker`              | `address` | Address of the offer maker, either an EOA or a Maker contract                      |
| `gasreq`             | `uint`    | Gas required by the offer (in gas units)                                           |
| `kilo_offer_gasbase` | `uint`    | Mangrove's `kilo_offer_gasbase` at the time the offer was posted (in 1k gas units) |
| `gasprice`           | `uint`    | The gas price covered by the offer bounty (in *Mwei* per gas unit)                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.mangrove.exchange/dev/protocol/technical-references/the-order-book/offer-views.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.