Moose / Documentation
Start here Monad

A guide to Moose

Learn what to expect when you trade with Moose.

Moose is a trading app on Monad, the network where your transactions take place. Start with how your wallet connects, what you need to approve, and who pays the network fees. Then learn how swaps, borrowing, and bots work.

Before your first trade

Connect the wallet that holds the tokens you want to trade. Moose gives it a personal smart account: a contract controlled by your wallet that carries out your trades and checks their permissions.

Where your swap funds go
  1. 01Pay from your walletSupplies the tokens you want to sell.
  2. 02Trade through your accountCarries out the swap using your permissions.
  3. 03Receive in your walletReceives the tokens you bought.
You don’t need to move your swap balance into a separate trading wallet. Margin collateral and MON set aside for gas are explained below.

Signing in for one-click trading

Connecting your wallet lets Moose see its address. Signing in asks your wallet to authorize a trading session for up to 24 hours. A temporary session key then signs supported trades, so you don't get a wallet popup each time.

The session key signs the trade; the tokens still come from and go to your connected wallet. It has limited permissions and is kept in an isolated part of your browser, without being sent to Moose servers.

To confirm each trade in your wallet instead, choose Sign each trade. Both modes use your personal smart account.

Why your wallet asks for approval

Before a token can leave your wallet, you must approve a token allowance: permission for your smart account to use that token, up to an amount you choose. You confirm this in your connected wallet, even with one-click trading enabled.

This extra wallet confirmation keeps you in control of token access. The session key cannot give itself permission to spend more of your wallet's tokens. You are approving your own personal smart account, rather than a universal router contract shared by all Moose users.

Choose Custom to set an amount, or Max for an unlimited allowance. Custom starts with the amount needed for that token in your current trade, which you can edit before approving. The approval itself does not move your tokens or place a trade. You may be prompted again when using a different token or when your remaining allowance is too low.

Getting MON ready for gas

Monad charges a network fee, called gas, to process transactions. Gas is paid in MON, the network's native token. Moose checks whether you qualify for gas sponsorship during sign-in.

If you qualify, Moose funds the session key and covers eligible one-click network fees, subject to available funds and limits. If you don't qualify, sign-in asks you to deposit MON from your connected wallet before one-click trading is ready.

The Total gas deposit field sets the total MON sent from your wallet. This amount tops up the session key when needed, and the remainder goes to your account's gas escrow. For example, a 5 MON deposit with a 2 MON session-key shortfall sends 2 MON to the key and 3 MON to escrow. The wallet's network fee is separate. Smaller deposits can partially top up the key; Moose may ask you to refill again before trading.

Sponsorship does not cover swap fees or loan interest. Token approvals and trades in Sign each trade mode are wallet transactions, so your connected wallet pays their network fees directly.

When you come back

Closing the browser ends access to the temporary session key. You'll need to sign in with your connected wallet again when you return. The key is not saved for your next visit, and a session also needs renewing after its 24-hour permission expires.

Signing out does not move your wallet funds, repay a loan, or remove existing token allowances. Open loans continue to accrue interest and carry liquidation risk while you're away.

Swaps, margin, and shorts

Before choosing a trade, it helps to know where the tokens you sell will come from:

Swap
Exchange tokens you already own. You pay from your wallet and receive the token you buy, with no loan to repay.
Margin
Set aside tokens as collateral to back a loan. Borrow tokens, then sell them for another token. The sale proceeds go to your wallet; the loan remains until you repay it, plus interest.
Short
Borrow and sell a token hoping its price falls, so you can buy it back for less and repay the loan. A rising price makes repayment more expensive.

With margin, your collateral stays in the lending market while it backs your debt. If it no longer provides enough backing, it can be sold to repay the loan—a risk called liquidation. The margin guide walks through an example and how to manage an open loan.

What the account checks

  • Your wallet stays in control of the account.
  • The session key can perform only the actions it has permission to use, before that permission expires.
  • Each swap must use the approved tokens and amounts, and meet your minimum received.
  • The account checks actual token balances to confirm what was paid and received.

Swapping tokens

A swap exchanges one token for another—for example, MON for USDC. Moose compares prices across markets and can spread your swap across several of them to find a better rate.

One swap can use several markets
Moose compares markets to look for a better overall rate.

Make your first swap

From choosing tokens to receiving them
  1. 01Choose tokensPick the token to pay with and the one to receive.
  2. 02Review the quoteEnter an amount. Check what you’ll receive, your minimum, and the fees.
  3. 03Confirm the swapApprove token access if prompted, then confirm your trade.
When the swap completes, the tokens you bought return to your wallet.

If prompted, confirm the token allowance in your connected wallet first. After that, one-click mode can sign supported swaps for you. Changing tokens or exceeding an allowance may require another wallet approval.

Firm quotes for xStocks

Moose first looks for a DEX route that can fill your whole trade within your price limits. When available for the asset, a firm quote can provide another way to trade. It is tied to your exact amount and expires after a short time.

Moose prepares and refreshes that quote before you press Send. Changing the amount starts a new quote. A still-valid quote can stay ready while its replacement loads; a closed market, expired quote, or changed trade can make Send unavailable.

Supported trades finish in one transaction, including a quote through USDC or a firm quote followed by a DEX swap. If a trade needs USDC first, Moose shows that as a separate funding action. Short and Loop also keep borrowing, token conversions and the trade together, and show wrapped reserve amounts separately when they differ from the token being traded.

When the price changes

The amount shown before you trade is an estimate, called a quote. Prices can move before your trade finishes. The difference between the quote and what you receive is called slippage.

Your slippage setting limits how much less you will accept. For a quote of 100 USDC with 1% slippage, you must receive at least 99 USDC after fees.

Example: 100 USDC quote, 1% slippage
Swap stopsWithin your limit
< 99Too little
99Your minimum
100The quote
101+A better price
If the swap cannot meet your minimum, it fails and is undone. A network fee may still apply.

Network fees

The Monad network charges a fee to process a transaction. This is often called gas. Moose's extra price checks can use more gas than a simpler swap.

Check the Network Fee row before confirming. Some one-click trades have this fee covered by Moose.

Borrowing & margin

On Moose, a margin trade is a token loan followed by a swap. You deposit tokens you own as collateral, or use collateral you already have. You then borrow a token and sell it for another token. Moose uses the Neverland lending market to hold your collateral and track the loan.

Opening a margin trade
  1. 01Add collateralSet aside tokens to back your loan.
  2. 02Borrow tokensTake a loan against that collateral.
  3. 03TradeSell the borrowed tokens and receive the proceeds in your wallet.
These steps complete together. If any step fails, the whole operation is undone.

The tokens you buy arrive in your connected wallet, but you still owe the borrowed token plus interest. Swapping the proceeds or closing Moose does not repay that debt. To finish the trade, you need enough of the borrowed token to repay the loan; then you can withdraw collateral if no other debt needs it.

How a short works

A short is a trade that benefits if a token's price falls. You borrow the token, sell it, then buy it back to repay the loan. If buying it back costs more, you lose money.

Example: borrow 10 tokens and sell them for $400
Buy them back for $320$80 gain before costs
Buy them back for $520$120 loss before costs
You still owe 10 tokens plus interest, whatever happens to their price. Fees and interest reduce any gain and add to any loss.

Understanding your loan

Loan-to-value (LTV) compares how much you owe with the value of your collateral. A higher LTV means less room for prices to move against you.

You owe$400
Collateral$1,000
Loan-to-value40% LTV

In Pro mode, select Margin and enter how much you want to borrow and sell. Moose selects existing collateral by default and shows how the trade changes the LTV across your whole portfolio.

To add collateral from your wallet, choose a token and either enter an amount or set a target LTV:

Enter a token amount
Your deposit amount stays fixed as prices change. The resulting LTV may move.
Set a target LTV
Moose adjusts the deposit as prices and your trade size change, accounting for your existing collateral and debt.

The target starts at 50%, or lower if the market requires it. For MON collateral, use WMON, the wrapped version of MON.

Watching your loan’s health

When a loan no longer has enough backing, collateral can be taken to repay it. This is called liquidation, and it also carries a penalty.

Your health factor helps you track this risk. At 1 or below, the loan can be liquidated. Being just above 1 leaves very little room for prices to change.

Health factor: room before liquidation
≤ 1Can be liquidated
> 1Above the cutoff
Larger buffer →
The closer this number gets to 1, the less room you have for an unfavorable price change.

Falling collateral prices, rising prices for the tokens you owe, and loan interest can all lower your health factor. Adding collateral or repaying debt can improve it, but the transaction may not finish in time to prevent liquidation.

Trading with bots

A bot places trades automatically using a strategy you choose. You decide which tokens it can trade and how much it can spend. Bots are available where your selected region supports them.

Set up a bot

From a strategy to a running bot
  1. 01Choose a strategyPick the tokens, trading rules, and spending limits.
  2. 02Add fundsApprove the tokens you want the bot to use.
  3. 03Start the botConfirm the setup to fund its account and allow it to trade.
The bot follows your settings automatically. Its trades can still lose money.

What your bot can do

Each bot holds its tokens in a separate account called a vault. Its permission limits which token pairs it can trade, the size of each trade, its total budget, and when it must stop.

Manage a bot

Fund
Add more tokens from your wallet.
Edit
Update the strategy or limits. Changing what the bot is allowed to do requires your wallet’s approval.
Pause
Stop scheduling new trades. Pausing keeps the bot’s trading permission in place.
Close
Remove the bot’s trading permission and return the tokens covered by it to your wallet.
Review
See completed trades, transaction links, remaining tokens, and recorded gains or losses.

Understanding fees

Moose may charge the fees below when enabled. Network fees, fees from the markets you trade on, loan interest, and liquidation penalties are separate costs.

When a swap beats your quote

If your swap returns more tokens than quoted, Moose can keep a share of the extra. This is a positive-slippage fee. It does not apply when the swap returns the quoted amount or less.

50%of the extra tokens, within the first 1% above your quote
Total fee capped at 0.5% of the quoted amount

You keep any further improvement beyond that first 1%. The amount you receive must still meet your slippage minimum after the fee.

Example: you were quoted 100 USDC
Before this fee100.60
Moose fee0.30
You receive100.30
If the swap returns 102 USDC before this fee, Moose takes at most 0.50 USDC and you receive 101.50 USDC.

When collateral earns interest

Collateral balances, withdrawal Max, and the “You receive” field show estimated amounts after fees. Enter the amount you want to receive; Moose includes the fee in the collateral redeemed. Final proceeds can change slightly as interest accrues before execution.

If your collateral earns interest, Moose can charge a fee on those earnings when you withdraw or use collateral to repay a loan. Your original deposit is excluded.

10%of the earnings you redeem
No earnings means no fee of this type
Example: a $1,000 deposit grows to $1,020
You earned$20
Fee rate10%
Moose fee$2
You withdraw $1,018 before other market effects: your $1,000 deposit plus $18 of earnings after the fee.

For a partial withdrawal, only the earnings in that withdrawal count, plus any unpaid fee from earlier repayments using collateral. Repaying with collateral records the fee on the earnings it uses and reserves enough collateral to pay it on a later withdrawal or close. A small withdrawal can go entirely toward that unpaid fee. Borrowing and repaying from your wallet do not incur this fee. Loan interest is a separate cost and does not reduce the earnings used to calculate it.

API

Build exact-input spot swaps on Monad with three public endpoints. Get a quote and a prepared transaction, then sign and send it from your own wallet. No API key, sign-in, wallet address or account deployment is required to request a quote.

Download the OpenAPI specification for complete request and response schemas. This API supports spot swaps only; it does not provide Perps, balances, positions, stop triggers, user history or transaction submission.

Get started

  1. Read configuration for the network, shared approval address and fee policy.
  2. Read the token list and convert your input amount to the token’s base units.
  3. Approve ERC-20 input from your wallet, then request a fresh quote.
  4. Sign the returned transaction locally and broadcast it through your RPC.

Funds stay in your wallet between swaps. The transaction sender pays the input and receives the output. Website Nexus balances are separate from the wallet balance used for direct API swaps.

GET /v1/config

Discover the current contracts, approval target and fee settings. No parameters or request body are needed.

curl --fail-with-body \
  https://api.moose.trade/v1/config
chainId
The network to use: 143 for Monad.
spender
The shared ERC-20 approval address. It equals aggregator.address and the quote’s transaction.to. Read it from configuration instead of hardcoding it.
nativeToken
The zero address, 0x0000000000000000000000000000000000000000, represents native MON.
Contracts
aggregator, aggregatorImplementation, directSwapPolicy, wrappedNative, quoteHelper and signerRegistry each include an address and runtime code hash.
quoteSigner
The public address that signs the quote embedded in your transaction. It is not your wallet signer.
Fee settings
surplusFeeBps, surplusFeeCapBps and feeCollector describe the current positive-surplus fee.
maxTransactionGas
The maximum outer transaction gas budget. Use the individual quote’s transaction.gas for your swap.

A successful configuration response does not guarantee that every pair is currently quotable.

GET /v1/tokens

Browse the website token catalog. Use tier=premium for the reviewed token set, tier=catalog for other discovered tokens, or omit it for both. Search with q using a symbol, name or exact contract address. No request body is needed.

curl --fail-with-body \
  'https://api.moose.trade/v1/tokens?tier=premium'

The response contains a tokens array and, when more results are available, nextCursor. Pass that value as cursor with the same q and tierto continue. Catalog entries are ordered by most recent update. limit defaults to 250 and accepts 1–500 catalog entries; native MON is added first on the first matching page unless tier=catalog is selected.

address
The token contract address, or the zero address for native MON. Use this address when requesting a quote.
symbol
The display name, such as MON, USDC or AUSD. Identify tokens by address in requests.
decimals
Convert human amounts to integer base units: 1 USDC with 6 decimals is "1000000"; 1 MON with 18 decimals is "1000000000000000000".

A listed token does not guarantee liquidity for every pair or size. MON and WMON normalize to the same routing asset, so a MON-to-WMON quote is not a supported swap.

POST /v1/quote

Request an exact-input swap. Moose simulates the full swap, including fees and the minimum output, without reading your wallet’s balance or allowance. Send Content-Type: application/json and exactly these four fields:

tokenIn · string
The input token address from /v1/tokens. Checksum casing is accepted; use the zero address for MON.
tokenOut · string
The output token address from /v1/tokens. It must differ from the input after MON/WMON normalization.
amountIn · string
An integer in input-token base units, from 20 to 2²⁵⁶ − 1, subject to route capacity. Use a decimal string, without decimal points, leading zeros, signs or exponent notation.
slippageBps · integer
Required, from 0 to 5000. 50 means 0.5%. This controls the signed minimum net output.

The following requests a quote for 1 MON into USDC with 0.5% slippage. It does not send a trade.

curl --fail-with-body \
  https://api.moose.trade/v1/quote \
  -H 'Content-Type: application/json' \
  --data '{
    "tokenIn": "0x0000000000000000000000000000000000000000",
    "tokenOut": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
    "amountIn": "1000000000000000000",
    "slippageBps": 50
  }'

Unknown fields are rejected, including owner, from, recipient and custom RPC URLs. Quote requests are limited to 65,536 bytes. Successful responses contain:

quote
amountIn, simulated net amountOut, signed minAmountOut, protocolFee, token metadata and slippage. The corresponding Formatted fields are for display; use base-unit strings for calculations.
transaction
chainId, to, data, value, gas and gasPrice. Value, gas and gas price are hexadecimal RPC quantities. The calldata already includes the complete trade and quote signature.
spender
The shared approval address, also returned by /v1/config.
trade & signature
The signed trade, its execution anchor, deadline, routes and backend signature. Preserve them unchanged; no reconstruction is needed when using transaction.data.
simulationBlock
The block number, hash and Unix-millisecond timestamp used for simulation.
observed
Gross input/output amounts seen in the simulation, per route and pool, before the protocol fee.
materialId & routesHash
Identifiers for quote-data correlation and the canonical routes.

The quote expires 20 seconds after the simulation block’s timestamp; less time remains when you receive it, and its block anchor can expire earlier. Request a new quote after approvals or any delay. Simulation confirms execution at that block, not your balance, approval or a future fill.

Approve & send a swap

  1. For an ERC-20 input, check your allowance to spender. If needed, call the token’s approve(spender, amountIn)from the same wallet that will send the swap, and wait for confirmation. Native MON needs no approval.
  2. Request a fresh quote and review the input, minimum output and fee.
  3. Supply your wallet’s nonce and sign the returned transaction locally. Preserve to, data, value and the supplied gas budget. Gas is a conservative limit, not measured usage; Monad charges against that limit. Keep enough MON for network gas, in addition to any native input amount.
  4. Broadcast through your RPC and read the transaction receipt there. Moose does not relay or track transactions through this API. If a broadcast times out, check the transaction hash and nonce before sending another trade.

ERC-20 input has transaction.value = "0x0". For native input, value equals the input amount in wei. Output returns to the transaction sender; a smart-contract caller requesting native output must be able to receive MON. The same quote may be used by another funded caller before expiry, but it can only spend that caller’s tokens.

Fees, limits & errors

quote.amountOut is already net of the simulated protocol fee. Moose charges a configured share of positive output surplus, capped relative to the signed route baseline; this is not a flat fee on the trade amount. Read the live rates from /v1/config. Fees cannot take output below the signed minimum. The actual fee is recorded in DirectSwapExecuted in your transaction receipt. Network gas is separate.

The edge allows 10 requests per second per IP, with a burst of 20 and at most 20 concurrent requests per IP. Shared regional limits are 40 requests per second (burst 40) and 64 concurrent requests across all clients. The API limits total quote work to four concurrent requests, each with a 30-second processing timeout. Responses are no-store.

400 · Invalid request
Fix the JSON, fields or values before retrying.
404 · Token or route missing
Check /v1/tokens. A supported pair may have no published route.
422 · Quote unavailable
The amount may exceed liquidity, material may be stale, or simulation may fail. Inspect error.code and error.retryable; lower the amount when appropriate.
429 · Rate or capacity limit
Back off. Honor Retry-After when present, and avoid retrying requests together in a burst.
503 · Temporarily unavailable
The quote source, chain checks or signing authority is unavailable. Retry a quote later with backoff.
{
  "error": {
    "code": "busy",
    "message": "Request concurrency is exhausted; retry shortly.",
    "retryable": true
  }
}

Match error.code, not message text. retryable means another quote request may succeed; it does not authorize blindly resending a signed transaction. Edge errors and unknown routes or methods may return plain text instead of this JSON shape.

Technical reference

For a closer look at market pricing, the system design, and the math behind each swap, explore the details below.