Class: Market

The Market class focuses on a Mangrove market. On-chain, markets are implemented as two offer lists, one for asks (base,quote), the other for bids (quote,base).

Market initialization needs to store the network name, so you cannot directly use the constructor. Instead of new Market(...), do await Market.connect(...).

See

connect

Properties

mgv

• mgv: Mangrove

Defined in

@mangrovedao/mangrove.js/src/market.ts:505

---

base

• base: Token

Defined in

@mangrovedao/mangrove.js/src/market.ts:506

---

quote

• quote: Token

Defined in

@mangrovedao/mangrove.js/src/market.ts:507

---

tickSpacing

• tickSpacing: number

Defined in

@mangrovedao/mangrove.js/src/market.ts:508

---

olKeyBaseQuote

• olKeyBaseQuote: OLKeyStruct

The OLKey for the base, quote offer list

Defined in

@mangrovedao/mangrove.js/src/market.ts:510

---

olKeyQuoteBase

• olKeyQuoteBase: OLKeyStruct

The OLKey for the quote, base offer list

Defined in

@mangrovedao/mangrove.js/src/market.ts:512

---

trade

• trade: Trade

Defined in

@mangrovedao/mangrove.js/src/market.ts:517

---

tradeEventManagement

• tradeEventManagement: TradeEventManagement

Defined in

@mangrovedao/mangrove.js/src/market.ts:518

---

prettyP

• prettyP: PrettyPrint

Defined in

@mangrovedao/mangrove.js/src/market.ts:519

---

minVolumeAsk

• Optional minVolumeAsk: Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:524

---

minVolumeBid

• Optional minVolumeBid: Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:525

Methods

connect

▸ connect(params): Promise<Market>

Connect to a market.

Parameters

Name	Type	Description
params	{ mgv: Mangrove } & Key & Partial<OptionalParams>	A set of parameters identifying the market on Mangrove to connect to.

Returns

Promise<Market>

A promise that resolves to a Market instance.

Defined in

@mangrovedao/mangrove.js/src/market.ts:532

---

close

▸ close(): void

Close a Market instance.

Returns

void

Defined in

@mangrovedao/mangrove.js/src/market.ts:611

---

initialize

▸ initialize(): Promise<void>

Initialize the market.

Returns

Promise<void>

Defined in

@mangrovedao/mangrove.js/src/market.ts:627

---

getOLKey

▸ getOLKey(ba): OLKeyStruct

Get the configuration of the specified offer list of the market.

Parameters

Name	Type	Description
ba	BA	bids or asks

Returns

OLKeyStruct

The configuration of the specified offer list of the market.

Defined in

@mangrovedao/mangrove.js/src/market.ts:692

---

getBook

▸ getBook(): Book

Return the two semibooks of this market.

Asks are standing offers to sell base and buy quote. Bids are standing offers to buy base and sell quote. All prices are in quote/base, all volumes are in base. Offers are ordered from best to worse from the taker perspective.

Returns

Book

Defined in

@mangrovedao/mangrove.js/src/market.ts:734

---

getSemibook

▸ getSemibook(ba): Semibook

Return the bids or asks semibook.

Parameters

Name	Type
ba	BA

Returns

Semibook

Defined in

@mangrovedao/mangrove.js/src/market.ts:747

---

requestBook

▸ requestBook(opts?): Promise<{ asks: Offer[] ; bids: Offer[] }>

Return the asks and bids semibook.

Parameters

Name	Type	Default value	Description
opts	BookOptions	bookOptsDefault	Options to filter the offers in the book.

Returns

Promise<{ asks: Offer[] ; bids: Offer[] }>

The asks and bids semibooks, with the offers that match the options.

Defined in

@mangrovedao/mangrove.js/src/market.ts:759

---

spread

▸ spread(): Promise<{ absoluteSpread: undefined ; relativeSpread: undefined ; tickSpread: undefined } | { absoluteSpread: Big ; relativeSpread: Big ; tickSpread: number }>

Gets the absolute, relative, and tick spread between bids and asks on the market.

Returns

Promise<{ absoluteSpread: undefined ; relativeSpread: undefined ; tickSpread: undefined } | { absoluteSpread: Big ; relativeSpread: Big ; tickSpread: number }>

Defined in

@mangrovedao/mangrove.js/src/market.ts:776

---

spread

▸ spread(market, bestAsk?, bestBid?): { absoluteSpread: undefined ; relativeSpread: undefined ; tickSpread: undefined } | { absoluteSpread: Big ; relativeSpread: Big ; tickSpread: number }

Gets the absolute, relative, and tick spread between a bid and an ask on the market.

Parameters

Name	Type
market	KeyResolvedForCalculation
bestAsk?	Object
bestAsk.price	BigSource
bestAsk.tick	number
bestBid?	Object
bestBid.price	BigSource
bestBid.tick	number

Returns

{ absoluteSpread: undefined ; relativeSpread: undefined ; tickSpread: undefined } | { absoluteSpread: Big ; relativeSpread: Big ; tickSpread: number }

Defined in

@mangrovedao/mangrove.js/src/market.ts:788

---

isActive

▸ isActive(): boolean

Is the market active?

Returns

boolean

Whether the market is active, i.e., whether both the asks and bids semibooks are active.

Defined in

@mangrovedao/mangrove.js/src/market.ts:813

---

isLive

▸ isLive(ba, offerId): Promise<boolean>

Is the offer corresponding to the given offerId in the book ba live?

Parameters

Name	Type	Description
ba	BA	Bids or asks.
offerId	number	An offer id to check.

Returns

Promise<boolean>

True, if a corresponding live offer was found, else false.

Defined in

@mangrovedao/mangrove.js/src/market.ts:824

---

isLiveOffer

▸ isLiveOffer(offer): boolean

Is the offer live?

Parameters

Name	Type	Description
offer	Offer	An offer to check.

Returns

boolean

True, if the offer is live, else false.

Defined in

@mangrovedao/mangrove.js/src/market.ts:834

---

getOfferProvision

▸ getOfferProvision(ba, gasreq, gasprice?): Promise<Big>

Gets the amount of ethers necessary to provision an offer on the market.

Parameters

Name	Type	Description
ba	BA	bids or asks
gasreq	number	gas required for the offer execution.
gasprice?	number	gas price to use for the calculation. If undefined, then Mangrove's current gas price is used.

Returns

Promise<Big>

the amount of ethers necessary to provision the offer.

Defined in

@mangrovedao/mangrove.js/src/market.ts:844

---

getBidProvision

▸ getBidProvision(gasreq, gasprice?): Promise<Big>

Gets the amount of ethers necessary to provision a bid on the market.

Parameters

Name	Type	Description
gasreq	number	gas required for the offer execution.
gasprice?	number	gas price to use for the calculation. If undefined, then Mangrove's current gas price is used.

Returns

Promise<Big>

the amount of ethers necessary to provision the offer.

Defined in

@mangrovedao/mangrove.js/src/market.ts:864

---

getAskProvision

▸ getAskProvision(gasreq, gasprice?): Promise<Big>

Gets the amount of ethers necessary to provision a bid on the market.

Parameters

Name	Type	Description
gasreq	number	gas required for the offer execution.
gasprice?	number	gas price to use for the calculation. If undefined, then Mangrove's current gas price is used.

Returns

Promise<Big>

the amount of ethers necessary to provision the offer.

Defined in

@mangrovedao/mangrove.js/src/market.ts:873

---

getMissingProvision

▸ getMissingProvision(ba, lockedProvision, gasreq, gasprice?): Promise<Big>

Gets the missing provision in ethers for an offer with the given parameters

Parameters

Name	Type	Description
ba	BA	bids or asks
lockedProvision	BigSource	the provision already locked with the offer
gasreq	number	gas required for the offer execution.
gasprice?	number	gas price to use for the calculation. If undefined, then Mangrove's current gas price is used.

Returns

Promise<Big>

the additional required provision, in ethers.

Defined in

@mangrovedao/mangrove.js/src/market.ts:884

---

bidInfo

▸ bidInfo(offerId): Promise<Offer>

Returns the offer info for the given offerId in the bids offer list.

Parameters

Name	Type	Description
offerId	number	id of the offer to get info for.

Returns

Promise<Offer>

the offer info for the given offerId.

Defined in

@mangrovedao/mangrove.js/src/market.ts:906

---

askInfo

▸ askInfo(offerId): Promise<Offer>

Returns the offer info for the given offerId in the asks offer list.

Parameters

Name	Type	Description
offerId	number	id of the offer to get info for.

Returns

Promise<Offer>

the offer info for the given offerId.

Defined in

@mangrovedao/mangrove.js/src/market.ts:915

---

offerInfo

▸ offerInfo(ba, offerId): Promise<Offer>

Returns struct containing offer details in the current market state.

Parameters

Name	Type	Description
ba	BA	bids or asks
offerId	number	id of the offer to get info for.

Returns

Promise<Offer>

the offer info for the given offerId.

Defined in

@mangrovedao/mangrove.js/src/market.ts:924

---

permit

▸ permit(action, data): Promise<ContractTransaction>

Sign permit data. If action="buy", will permit buying base with spender's quote token. If action="sell", will permit buying quote with spender's base token.

Parameters

Name	Type	Description
action	"buy" | "sell"	"buy" or "sell"
data	Omit<SimplePermitData, "outbound_tkn" | "inbound_tkn">	permit data

Returns

Promise<ContractTransaction>

a promise that resolves to the permit signature.

See

Mangrove.permit

Defined in

@mangrovedao/mangrove.js/src/market.ts:937

---

buy

▸ buy(params, overrides?): Promise<Transaction<OrderResult>>

Market buy order. Will attempt to buy base token using quote tokens.

Parameters

Name	Type	Description
params	TradeParams	Trade parameters - see Market.TradeParams.
overrides	Overrides	ethers overrides for the transaction.

Returns

Promise<Transaction<OrderResult>>

a promise that resolves to the transaction response and the result of the trade.

Remarks

Will stop if

• book is empty, or
• price no longer good, or
• wants tokens have been bought.

Example

const market = await mgv.market({base:"USDC",quote:"DAI"};
market.buy({volume: 100, price: '1.01'}) //use strings to be exact

Defined in

@mangrovedao/mangrove.js/src/market.ts:979

---

sell

▸ sell(params, overrides?): Promise<Transaction<OrderResult>>

Market sell order. Will attempt to sell base token for quote tokens.

Parameters

Name	Type	Description
params	TradeParams	Trade parameters - see Market.TradeParams.
overrides	Overrides	ethers overrides for the transaction.

Returns

Promise<Transaction<OrderResult>>

a promise that resolves to the transaction response and the result of the trade.

Remarks

Will stop if

• book is empty, or
• price no longer good, or -gives tokens have been sold.

Example

const market = await mgv.market({base:"USDC",quote:"DAI"})
market.sell({volume: 100, price: 1})

Defined in

@mangrovedao/mangrove.js/src/market.ts:1006

---

gasEstimateBuy

▸ gasEstimateBuy(params): Promise<BigNumber>

Estimate amount of gas for a buy order corresponding to the given trade parameters.

Parameters

Name	Type	Description
params	TradeParams	Trade parameters.

Returns

Promise<BigNumber>

a gas estimate for the trade.

See

• buy for the corresponding trade method.
• Market.TradeParams for a description of trade parameters

Defined in

@mangrovedao/mangrove.js/src/market.ts:1019

---

gasEstimateSell

▸ gasEstimateSell(params): Promise<BigNumber>

Estimate amount of gas for a sell order corresponding to the given trade parameters.

Parameters

Name	Type	Description
params	TradeParams	Trade parameters.

Returns

Promise<BigNumber>

a gas estimate for the trade.

See

• sell for the corresponding trade method.
• Market.TradeParams for a description of trade parameters

Defined in

@mangrovedao/mangrove.js/src/market.ts:1030

---

updateRestingOrder

▸ updateRestingOrder(ba, params, overrides?): Promise<Transaction<void>>

Update a resting order posted by MangroveOrder.

Parameters

Name	Type	Description
ba	BA	whether the offer is a bid or ask
params	UpdateRestingOrderParams	update parameters - see Market.UpdateRestingOrderParams
overrides	Overrides	overrides for the transaction

Returns

Promise<Transaction<void>>

a promise that resolves to the transaction response and the result of the update.

Defined in

@mangrovedao/mangrove.js/src/market.ts:1042

---

retractRestingOrder

▸ retractRestingOrder(ba, id, deprovision?, overrides?): Promise<Transaction<void>>

Retract a resting order posted by MangroveOrder.

Parameters

Name	Type	Default value	Description
ba	BA	undefined	whether the offer is a bid or ask
id	number	undefined	the offer id
deprovision	boolean	false	whether to deprovision the offer. If true, the offer's provision will be returned to the maker's balance on Mangrove.
overrides	Overrides	{}	overrides for the transaction

Returns

Promise<Transaction<void>>

Defined in

@mangrovedao/mangrove.js/src/market.ts:1057

---

clean

▸ clean(params, overrides?): Promise<{ result: Promise<CleanResult> ; response: Promise<ContractTransaction> }>

Clean a set of given offers.

Parameters

Name	Type	Description
params	CleanParams	Parameters for the cleaning, specifying the target offers, the side of the market to clean, and optionally the taker to impersonate.
overrides	Overrides	ethers overrides for the transaction.

Returns

Promise<{ result: Promise<CleanResult> ; response: Promise<ContractTransaction> }>

a promise that resolves to the transasction response and the result of the cleaning.

See

Market.CleanParams for a description of params.

Defined in

@mangrovedao/mangrove.js/src/market.ts:1074

---

getRawCleanParams

▸ getRawCleanParams(params): Promise<RawCleanParams>

Gets parameters to send to function market.mgv.cleanerContract.cleanByImpersonation.

Parameters

Name	Type	Description
params	CleanParams	Parameters for the cleaning, specifying the target offers, the side of the market to clean, and optionally the taker to impersonate

Returns

Promise<RawCleanParams>

a promise that resolves to the raw parameters to send to the cleaner contract

Remarks

In more detail, the parameters should be an object with the following fields: targets: an array of offerId: the offer to be cleaned takerWants: the amount of base token (for asks) or quote token (for bids) the taker wants tick: the of the offer to be cleaned gasreq: the maximum gasreq the taker/cleaner, wants to use to clean the offer, has to be at least the same as the gasreq of the offer in order for it be cleaned ba: whether to clean asks or bids taker: specifies what taker to impersonate, if not specified, the caller of the function will be used

Defined in

@mangrovedao/mangrove.js/src/market.ts:1102

---

estimateGas

▸ estimateGas(bs, volume): Promise<BigNumber>

Estimate amount of gas for a buy or sell order for the given volume.

Parameters

Name	Type	Description
bs	BS	buy or sell
volume	BigNumber	volume to trade

Returns

Promise<BigNumber>

an estimate of the gas required for the trade

Defined in

@mangrovedao/mangrove.js/src/market.ts:1114

---

simulateGas

▸ simulateGas(ba, maxTick, fillVolume, fillWants): Promise<BigNumber>

Uses Semibook.simulateMarketOrder to simulate the gas required for a market order. An overhead of 50% is added to account for changes to the book and failing offers.

Parameters

Name	Type	Description
ba	BA	bids or asks
maxTick	number	the maximum to reach for the market order.
fillVolume	BigNumber	the amount to fill (wants or gives)
fillWants	boolean	whether to fill wants or gives

Returns

Promise<BigNumber>

Defined in

@mangrovedao/mangrove.js/src/market.ts:1141

---

estimateVolume

▸ estimateVolume(params): Promise<VolumeEstimate>

Volume estimation for buying or selling:

If you say estimateVolume({given:100,what:"base",to:"buy"}),

an estimate of how much quote token you would have to spend to get 100 base tokens will be returned.

If you say estimateVolume({given:10,what:"quote",to:"sell"}),

an estimate of how much base tokens you'd have to buy in order to spend 10 quote tokens will be returned.

Parameters

Name	Type	Description
params	VolumeParams	Parameters for the volume estimation - see Market.VolumeParams

Returns

Promise<VolumeEstimate>

a promise that resolves to the volume estimation.

Defined in

@mangrovedao/mangrove.js/src/market.ts:1181

---

estimateVolumeToReceive

▸ estimateVolumeToReceive(params): Promise<VolumeEstimate>

Convenience method: Estimate volume to be received given an amount of base/quote you are ready to spend.

Parameters

Name	Type	Description
params	DirectionlessVolumeParams	Parameters for the volume estimation - see Market.DirectionlessVolumeParams

Returns

Promise<VolumeEstimate>

a promise that resolves to the volume estimation.

See

estimateVolume

Defined in

@mangrovedao/mangrove.js/src/market.ts:1201

---

estimateVolumeToSpend

▸ estimateVolumeToSpend(params): Promise<VolumeEstimate>

Convenience method: Estimate volume to be spent given an amount of base/quote you want to receive.

Parameters

Name	Type	Description
params	DirectionlessVolumeParams	Parameters for the volume estimation - see Market.DirectionlessVolumeParams

Returns

Promise<VolumeEstimate>

a promise that resolves to the volume estimation.

See

estimateVolume

Defined in

@mangrovedao/mangrove.js/src/market.ts:1214

---

config

▸ config(): Object

Return config local to a market.

Returns

Object

The config for the asks and bids side of the market.

Name	Type
asks	LocalConfig
bids	LocalConfig

Remarks

• Amounts are converted to plain numbers.
• density is converted to public token units per gas used
• fee remains in basis points of the token being bought

Defined in

@mangrovedao/mangrove.js/src/market.ts:1230

---

consoleAsks

▸ consoleAsks(filter?): void

Pretty prints the current state of the asks of the market

Parameters

Name	Type
filter?	prettyPrintFilter

Returns

void

Defined in

@mangrovedao/mangrove.js/src/market.ts:1241

---

consoleBids

▸ consoleBids(filter?): void

Pretty prints the current state of the bids of the market

Parameters

Name	Type
filter?	prettyPrintFilter

Returns

void

Defined in

@mangrovedao/mangrove.js/src/market.ts:1246

---

prettyPrint

▸ prettyPrint(ba, filter): void

Pretty prints the current state of the asks or bids of the market

Parameters

Name	Type
ba	BA
filter	prettyPrintFilter

Returns

void

Defined in

@mangrovedao/mangrove.js/src/market.ts:1251

---

subscribe

▸ subscribe(cb): void

Subscribe to order book updates.

Parameters

Name	Type	Description
cb	MarketCallback<void>	a callback, which gets called whenever the order book is updated.

Returns

void

Remarks

The first argument of cb, event, is a summary of the event. It has the following properties:

• type the type of change. May be: "OfferWrite": an offer was inserted or moved in the book. "OfferFail", "OfferSuccess", "OfferRetract": an offer was removed from the book because it failed, succeeded, or was canceled.

• ba is either "bids" or "asks". The offer concerned by the change is either an ask (an offer for base asking for quote) or a bid (an offer for quoteasking forbase`).

• offer is information about the offer, see type Offer.

• taker, takerWants, takerGives (for "OfferFail" and "OfferSuccess" only): address of the taker who executed the offer as well as the volumes that were requested by the taker.

• mgvData : extra data from mangrove and the maker contract. See the Mangrove contracts documentation for the list of possible status codes.

opts may specify the maximum of offers to read initially, and the chunk size used when querying the reader contract (always ran locally).

Example

const market = await mgv.market({base:"USDC",quote:"DAI"}
market.subscribe((event,utils) => console.log(event.type, utils.book()))

Note

Only one subscription may be active at a time.

Defined in

@mangrovedao/mangrove.js/src/market.ts:1295

---

once

▸ once<T>(cb, filter?): Promise<T>

Returns a promise which is fulfilled after execution of the callback.

Type parameters

Name
T

Parameters

Name	Type
cb	MarketCallback<T>
filter?	MarketFilter

Returns

Promise<T>

Defined in

@mangrovedao/mangrove.js/src/market.ts:1302

---

unsubscribe

▸ unsubscribe(cb): void

Stop calling a user-provided callback function on book-related events.

Parameters

Name	Type
cb	StorableMarketCallback

Returns

void

Defined in

@mangrovedao/mangrove.js/src/market.ts:1316

---

getOutboundInbound

▸ getOutboundInbound(ba): Object

Determine which token will be Mangrove's outbound/inbound depending on whether you're working with bids or asks.

Parameters

Name	Type	Description
ba	BA	bids or asks

Returns

Object

the outbound and inbound tokens.

Name	Type
outbound_tkn	Token
inbound_tkn	Token

Defined in

@mangrovedao/mangrove.js/src/market.ts:1324

---

getOutboundInbound

▸ getOutboundInbound<T>(ba, base, quote): Object

Determine which token will be Mangrove's outbound/inbound depending on whether you're working with bids or asks.

Type parameters

Name
T

Parameters

Name	Type	Description
ba	BA	bids or asks
base	T	base token
quote	T	quote token

Returns

Object

the outbound and inbound tokens.

Name	Type
outbound_tkn	T
inbound_tkn	T

Defined in

@mangrovedao/mangrove.js/src/market.ts:1337

---

getBaseQuoteVolumes

▸ getBaseQuoteVolumes(ba, gives, wants): Object

Determine whether gives or wants will be baseVolume/quoteVolume depending on whether you're working with bids or asks.

Parameters

Name	Type	Description
ba	BA	bids or asks
gives	Big	amount of token to give
wants	Big	amount of token to receive

Returns

Object

the base and quote volumes.

Name	Type
baseVolume	Big
quoteVolume	Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:1357

---

getWantsForPrice

▸ getWantsForPrice(ba, gives, price): Big

Determine the wants from gives and price depending on whether you're working with bids or asks.

Parameters

Name	Type
ba	BA
gives	Big
price	Big

Returns

Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:1369

---

getGivesForPrice

▸ getGivesForPrice(ba, wants, price): Big

Determine the gives from wants and price depending on whether you're working with bids or asks.

Parameters

Name	Type
ba	BA
wants	Big
price	Big

Returns

Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:1374

---

getGivesWantsForVolumeAtPrice

▸ getGivesWantsForVolumeAtPrice(ba, volume, price): Object

Determine gives and wants from a volume (in base) and a price depending on whether you're working with bids or asks.

Parameters

Name	Type	Description
ba	BA	bids or asks
volume	Big	volume of the offer
price	Big	price of the offer

Returns

Object

the gives and wants

Name	Type
gives	Big
wants	Big

Defined in

@mangrovedao/mangrove.js/src/market.ts:1384

---

getDisplayDecimalsForPriceDifferences

▸ getDisplayDecimalsForPriceDifferences(): number

Determine the first decimal place where the smallest price difference between neighboring offers in the order book cache is visible.

Returns

number

Defined in

@mangrovedao/mangrove.js/src/market.ts:1398

---

getDisplayDecimalsForPriceDifferences

▸ getDisplayDecimalsForPriceDifferences(offers): number

Determine the first decimal place where the smallest price difference between neighboring offers is visible.

Parameters

Name	Type	Description
offers	Offer[]	offers to consider

Returns

number

the first decimal place where the smallest price difference between neighboring offers is visible.

Defined in

@mangrovedao/mangrove.js/src/market.ts:1410