> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate tokenized equities (xStocks)

> Read balances, handle dividends and splits, wrap, price, and trade xStocks on Monad

[xStocks](https://xstocks.fi/) are ERC-20 tokens that track listed stocks and ETFs. They are issued by Backed directly on Monad mainnet (chain ID `143`), not bridged from another chain. As of November 11, 2026, the xStocks API lists more than 1,500 assets on Monad.

This guide covers what is different about integrating xStocks compared with an ordinary ERC-20:

* Each equity has two tokens: a rebasing base token and a non-rebasing wrapped token.
* Balances of the base token change on dividends and splits without any transfer.
* Balance changes are scheduled on-chain a short time ahead, and the price feeds stop updating on weekends.

> [!NOTE]
>
> xStocks are subject to the issuer's eligibility and jurisdiction restrictions. For example, they are not offered to U.S. persons. Check the [xStocks documentation](https://docs.xstocks.fi/) before offering them in your application.

## Choose the right token

Every xStock has a base token (for example `SPYx`) and a wrapped token (`wSPYx`).

| | Base token | Wrapped token |
| - | - | - |
| Standard | ERC-20 | ERC-4626 vault over the base token |
| Balance after a dividend or split | Changes. `balanceOf()` is rescaled for every holder | Unchanged |
| What one token represents | One share of the underlying | A fixed internal amount of the base token, redeemable for `multiplier` base tokens |
| Price source | Market price of the underlying | [Chainlink feeds](#price-wrapped-tokens-with-chainlink) for the listed tickers |
| Listed on 1inch, traded on Kuru | Yes | No |

Use the **base token** for anything a user sees or trades: wallet balances and swap UIs. One `SPYx` tracks one share of SPY at the price shown on any market data site.

Use the **wrapped token** inside any contract that records balances in its own storage: lending markets, vaults, and AMM pools. A contract that caches base-token balances goes out of sync when the multiplier changes. In a Uniswap v2-style pool, for example, the extra tokens from a dividend sit outside the pool's reserves until someone calls `sync()` or takes them with `skim()`.

## Find token addresses

The xStocks API is the source of truth for addresses. Public endpoints need no API key.

```bash theme={null}
curl "https://api.xstocks.fi/api/v2/public/assets?network=Monad&page=0"
```

The response is paginated, 100 assets per page. Increment `page` until `page.hasNextPage` is `false`.

`network=Monad` limits the list to assets that have a Monad deployment. It does not trim each asset's `deployments` array, which still has an entry for every network the asset is on, such as Solana and BNB Chain. Select the entry with `chainId` `143` yourself:

```bash theme={null}
curl -s "https://api.xstocks.fi/api/v2/public/assets?network=Monad&page=0" \
  | jq '.nodes[] | {symbol, monad: (.deployments[] | select(.chainId == 143) | {address, wrapperAddressV2})}'
```

The Monad entry looks like this:

```json theme={null}
{
  "address": "0x90a2a4c76b5d8c0bc892a69ea28aa775a8f2dd48",
  "network": "Monad",
  "chainId": 143,
  "wrapperAddressV2": "0xe7e553cd128f0011777323a0b44a7b96ea1cb540",
  "supportsAtomicSwaps": true,
  "stablecoins": [
    {
      "symbol": "USDC",
      "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
      "decimals": 6,
      "issuance": true,
      "redemption": true
    }
  ]
}
```

* `address` is the base token.
* `wrapperAddressV2` is the wrapped token. A few assets have no wrapper yet, so handle a missing field.
* `stablecoins` lists the tokens accepted for issuance and redemption. On Monad this is [USDC](https://docs.monad.xyz/developer-essentials/network-information/tokens-and-bridges.md).

To fetch a single asset, use `GET /api/v2/public/assets/{SYMBOL}`. It returns the deployments on every network.

Before you rely on a wrapper address, call `asset()` on it and confirm that it returns the base token.

### Addresses for the most liquid tickers

Base and wrapped tokens both have 18 decimals.

| Ticker | Underlying | Base token | Wrapped token |
| - | - | - | - |
| `SPYx` | SPDR S\&P 500 ETF | [`0x90A2a4c76b5D8c0bc892A69EA28Aa775a8f2dD48`](https://monadvision.com/token/0x90A2a4c76b5D8c0bc892A69EA28Aa775a8f2dD48) | [`0xE7E553Cd128F0011777323A0b44a7b96EA1CB540`](https://monadvision.com/token/0xE7E553Cd128F0011777323A0b44a7b96EA1CB540) |
| `QQQx` | Invesco QQQ (Nasdaq-100) ETF | [`0xa753A7395cAe905Cd615Da0B82A53E0560f250af`](https://monadvision.com/token/0xa753A7395cAe905Cd615Da0B82A53E0560f250af) | [`0x4C1AE29c159838fC1b224636E28E086EB69101f7`](https://monadvision.com/token/0x4C1AE29c159838fC1b224636E28E086EB69101f7) |
| `SMHx` | VanEck Semiconductor ETF | [`0x8D512a03600981B8e86556fd5C0FbDd726Fe1821`](https://monadvision.com/token/0x8D512a03600981B8e86556fd5C0FbDd726Fe1821) | [`0x23c4BDDea5e7E284fB4027c6050bC5E6f7FaE23f`](https://monadvision.com/token/0x23c4BDDea5e7E284fB4027c6050bC5E6f7FaE23f) |
| `EWYx` | iShares MSCI South Korea ETF | [`0x299c95Eb52BFd5Bc98d924bCE17197b64864589B`](https://monadvision.com/token/0x299c95Eb52BFd5Bc98d924bCE17197b64864589B) | [`0x021b40617982074748C81a19d22046CC2548C3bE`](https://monadvision.com/token/0x021b40617982074748C81a19d22046CC2548C3bE) |
| `SGOVx` | iShares 0-3 Month Treasury Bond ETF | [`0x2daFA4732c8c1b25701a33B05F10f437F9599326`](https://monadvision.com/token/0x2daFA4732c8c1b25701a33B05F10f437F9599326) | [`0x4Ac39e0881e5967822cCE9d166D1b7Ac12402ba1`](https://monadvision.com/token/0x4Ac39e0881e5967822cCE9d166D1b7Ac12402ba1) |
| `NVDAx` | NVIDIA | [`0xc845b2894dBddd03858fd2D643B4eF725fE0849d`](https://monadvision.com/token/0xc845b2894dBddd03858fd2D643B4eF725fE0849d) | [`0xa8ddb5Cd96b5222AFe198316E9A57CAA642850D5`](https://monadvision.com/token/0xa8ddb5Cd96b5222AFe198316E9A57CAA642850D5) |
| `TSLAx` | Tesla | [`0x8aD3c73F833d3F9A523aB01476625F269aEB7Cf0`](https://monadvision.com/token/0x8aD3c73F833d3F9A523aB01476625F269aEB7Cf0) | [`0xc3FdBe3A68EE5dE461D30415a8165cf9Aefe1171`](https://monadvision.com/token/0xc3FdBe3A68EE5dE461D30415a8165cf9Aefe1171) |

## Handle dividends and splits

xStocks do not pay dividends in cash. The issuer reinvests each dividend into more of the underlying, and every holder's token balance grows to match. Splits and reverse splits rescale balances the same way.

The base token implements this with a single **multiplier** shared by all holders:

```text theme={null}
balanceOf(account) = sharesOf(account) × multiplier
```

* `sharesOf(account)` is the internal balance. It changes only on transfer, mint, or burn.
* `balanceOf(account)` is the balance in shares of the underlying. It changes whenever the multiplier does.
* `transfer()` and `approve()` take amounts in `balanceOf()` units, as with any ERC-20. The token converts the amount to shares, so the amount that moves can be 1 wei less than requested.
* Each transfer emits `Transfer` with the `balanceOf()` amount and `TransferShares` with the internal amount.

### Read the multiplier

`getCurrentMultiplier()` returns three values. The first is the multiplier in effect now, scaled by 1e18. It switches to a scheduled value in the first block at or after the activation time.

```ts theme={null}
import { createPublicClient, http, parseAbi } from "viem";
import { monad } from "viem/chains";

const client = createPublicClient({ chain: monad, transport: http() });

const SPYx = "0x90A2a4c76b5D8c0bc892A69EA28Aa775a8f2dD48";
const account = "0x..."; // the holder to look up

const abi = parseAbi([
  "function getCurrentMultiplier() view returns (uint256 currentMultiplier, uint256 periodsPassed, uint256 currentMultiplierNonce)",
  "function sharesOf(address account) view returns (uint256)",
  "function balanceOf(address account) view returns (uint256)",
]);

const [multiplier] = await client.readContract({
  address: SPYx,
  abi,
  functionName: "getCurrentMultiplier",
});
// 1007474126658766000n on November 16, 2026, a multiplier of about 1.0075

const shares = await client.readContract({
  address: SPYx,
  abi,
  functionName: "sharesOf",
  args: [account],
});
```

### Know when the multiplier changes

The issuer schedules each new multiplier in a transaction that sets an activation time. At that time the new value takes effect without a further transaction. Dividend-paying equities change a few times a year.

Do not assume a fixed time of day or a long notice period. The xStocks docs give 00:30 UTC on the day after the ex-date as the standard, but past changes have also activated at 23:55 UTC and at other times, including during the trading day. On Monad, the two `SPYx` changes in October 2026 were scheduled 3 hours 15 minutes and 30 minutes before they activated.

#### Watch the token contract

The base token exposes the schedule on-chain.

| Function or event | What it tells you |
| - | - |
| `MultiplierScheduled(uint256 newMultiplier, uint256 activationTime)` | Emitted when the issuer schedules a change. This is the advance signal. |
| `newMultiplier()` and `newMultiplierActivationTime()` | The scheduled value and its Unix activation time. The activation time stays set after it passes and resets to `0` on the next token transfer. |
| `multiplierUpdates(uint256 index)` and `multiplierUpdatesLength()` | The history of changes on this chain: previous multiplier, new multiplier, activation time. |
| `MultiplierUpdated(uint256 value)` | Emitted by the first token transfer after an activation. For the two `SPYx` changes above it fired about 12 hours and 2 hours late. Do not use it for timing. |

```ts theme={null}
const scheduleAbi = parseAbi([
  "event MultiplierScheduled(uint256 newMultiplier, uint256 activationTime)",
  "function newMultiplierActivationTime() view returns (uint256)",
]);

// The scheduling transaction for the October 30, 2026 change.
// The public RPC accepts at most 100 blocks per eth_getLogs call.
const logs = await client.getLogs({
  address: SPYx,
  event: scheduleAbi[0],
  fromBlock: 117996000n,
  toBlock: 117996099n,
});
// logs[0].args: { newMultiplier: 1005732155949979200n, activationTime: 1793404500n }
```

#### Poll the xStocks API

The API publishes the current multiplier and, according to the xStocks docs, any pending change:

```bash theme={null}
curl "https://api.xstocks.fi/api/v2/public/assets/SPYx/multiplier?network=Monad"
```

```json theme={null}
{
  "currentMultiplier": 1.007474126658766,
  "newMultiplier": 0,
  "activationDateTime": 0,
  "reason": null
}
```

`newMultiplier` and `activationDateTime` are `0` when no change is scheduled. Past changes are available at `/api/v2/public/assets/{SYMBOL}/multiplier/history?network=Monad`.

`network` is a required parameter on both endpoints, but it does not change the result. The multiplier and its history are the same on every network.

#### Rules for tracking balances

* **Take advance notice from `MultiplierScheduled` or from the API.** Nothing is emitted at the activation time itself, and `MultiplierUpdated` arrives late.
* **Do not reconstruct base-token balances from `Transfer` events alone.** Index `TransferShares` or `sharesOf()` amounts and apply the current multiplier, or re-read `balanceOf()` after each activation.
* **Avoid the activation window.** xStocks recommends that venues and protocols pause interactions with a token for about 15 minutes before and after its activation time.

## Wrap and unwrap

The wrapped token is a standard ERC-4626 vault.

| Action | Function |
| - | - |
| Wrap | `deposit(assets, receiver)` or `mint(shares, receiver)` |
| Unwrap | `redeem(shares, receiver, owner)` or `withdraw(assets, receiver, owner)` |
| Convert between the two | `convertToAssets(shares)` and `convertToShares(assets)` |

`assets` are base tokens in `balanceOf()` units. `shares` are wrapped tokens. Wrapped shares equal the internal (`sharesOf()`) amount deposited, so `convertToAssets(1e18)` returns the current multiplier.

```ts theme={null}
import { erc20Abi, erc4626Abi, parseUnits } from "viem";

const wSPYx = "0xE7E553Cd128F0011777323A0b44a7b96EA1CB540";
const amount = parseUnits("10", 18); // 10 SPYx

// walletClient is a viem wallet client for the depositor
await walletClient.writeContract({
  address: SPYx,
  abi: erc20Abi,
  functionName: "approve",
  args: [wSPYx, amount],
});

await walletClient.writeContract({
  address: wSPYx,
  abi: erc4626Abi,
  functionName: "deposit",
  args: [amount, walletClient.account.address],
});
```

You can also wrap and unwrap in the [xStocks DeFi dashboard](https://defi.xstocks.fi/wrap).

> [!WARNING]
>
> The vault's conversion rate is not a price. To value a wrapped balance, use an independent price for the wrapped token or multiply `convertToAssets(shares)` by an independent price for the underlying.

## Price wrapped tokens with Chainlink

Chainlink publishes USD price feeds on Monad for six wrapped xStocks. Each feed returns the price of one wrapped token, which is the price of the underlying multiplied by the current multiplier. Feeds use the standard `AggregatorV3Interface` and have 8 decimals.

| Feed | Proxy address |
| - | - |
| `wSPYx / USD` | `0x2e2dA5717eDE960F8b77Af4cFcBDC4Ca3099006D` |
| `wQQQx / USD` | `0x7CA45B17D8D43059a222dEC5d991B613F61c02d9` |
| `wNVDAx / USD` | `0x03ffa4673c060339E6a8E5Ba1a12B3301c966bf0` |
| `wTSLAx / USD` | `0xE42022cCe1913626AE4297B99291d3Ba24Cc9281` |
| `wSPCXx / USD` | `0x7577154038de77668d0188baF47707EDcd86d0b3` |
| `wEWYx / USD` | `0x54D1645F9C1338f63407Fa64156eCeD9e195AB25` |

```solidity theme={null}
import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";

AggregatorV3Interface feed = AggregatorV3Interface(0x2e2dA5717eDE960F8b77Af4cFcBDC4Ca3099006D);
(, int256 answer,, uint256 updatedAt,) = feed.latestRoundData();
// answer is the wSPYx price in USD with 8 decimals
```

These feeds do not update while the market is closed for the weekend. The `wSPYx` feed published no rounds between Saturday, November 14, 2026 at 00:40 UTC and Monday, November 16 at 01:00 UTC, a gap of 48 hours. A fixed one-hour staleness check on `updatedAt` therefore reverts all weekend. Decide how borrows and liquidations behave during that gap, when the last price can be far from where the market reopens.

To price a base token, divide the wrapped price by the multiplier. For other oracle providers on Monad, see [Oracles](https://docs.monad.xyz/tooling-and-infra/oracles.md).

## Trade and source liquidity

| Route | How it works | Access |
| - | - | - |
| Aggregator | [1inch](https://docs.monad.xyz/tooling-and-infra/dex-aggregators.md#1inch) lists the base token of every xStock on Monad. | Any Monad user |
| Order book | [Kuru](#trade-on-an-order-book) has USDC markets for five xStocks. | Any Monad user |
| RFQ (xChange) | The issuer signs a firm quote for a ticker, side, and size, and the swap against USDC settles in one transaction. | API key from xStocks |
| Bridge | Move xStocks you hold on another chain with the [xStocks bridge](https://defi.xstocks.fi/bridge). | Holders on other chains |

### Swap through an aggregator

The 1inch token list for Monad includes the base token of all 1,516 xStocks and none of the wrapped tokens (as of November 16, 2026). Quote and swap the base token, and wrap afterwards if your contract needs the wrapped form.

Equities do not trade around the clock. The `trading` object on each asset in the xStocks API reports `openNow`, `nextChangeAt`, and the order limits for each session in `limitsPerPeriod`. For `SPYx`, the maximum order value in the `closed` session is `0`.

### Trade on an order book

[Kuru](https://www.kuru.io/) runs on-chain order books for five xStocks on Monad mainnet. Each market trades the base token against USDC.

| Market | Order book address |
| - | - |
| `SPYx/USDC` | `0xBb180c8B6D3eE0b4316B224C53B80dC4e354d24F` |
| `QQQx/USDC` | `0xEdf008258139ee23cf2bDB9C360f69131dC72708` |
| `NVDAx/USDC` | `0xf3FB2ec6ffb2A24506769bfaA3aD9B1EeB7D41Eb` |
| `TSLAx/USDC` | `0xf884c7631a7150F28c139a3A9f8B669258b5b285` |
| `EWYx/USDC` | `0xED3727e833200c849fbd18e15eD0D091c9B0F3aF` |

For the remaining contract addresses, market parameters, and fees, see Kuru's [mainnet deployments](https://docs.kuru.io/deployments/mainnet). To place orders, see the [Kuru SDK quickstart](https://docs.kuru.io/sdk/quickstart).

> [!WARNING]
>
> Kuru holds deposited tokens in a shared custody contract and tracks each account's balance internally. Kuru's [mainnet deployment record](https://gist.github.com/devblixt/0093a81e9fc21b6c96e74ac3d3eb08e9) states that "this deployment does not automatically reconcile issuer rebases with AccountCore's internal balances." Ask Kuru how dividends and splits are credited before you hold xStocks there across a multiplier change.

### Integrate xChange directly

Market makers and venues can request the issuer's quotes from the xChange API. The xChange endpoints return `401` without an API key. According to the xStocks docs, you also register your wallet, request a signed quote, and submit it to the xStocks swap contract before it expires (60 seconds by default). See the [xChange integration guide](https://docs.xstocks.fi/developers/xchange-atomic-rfq).

## Integration checklist

* Display and quote the base token. Hold the wrapped token in contracts that store balances.
* Load addresses from the xStocks API, select the deployment with `chainId` `143`, and verify `asset()` on each wrapper.
* Track `sharesOf()` or re-read `balanceOf()` after every multiplier activation.
* Watch `MultiplierScheduled` or poll the multiplier endpoint, and pause around each activation time.
* Price wrapped collateral from an oracle, never from the vault's conversion rate.
* Set staleness rules that account for the weekend gap in equity price feeds.
* Check the issuer's eligibility restrictions for your users.

## Resources

* [xStocks developer docs](https://docs.xstocks.fi/developers)
* [Multipliers](https://docs.xstocks.fi/developers/multipliers)
* [Wrapped xStocks](https://docs.xstocks.fi/developers/wrapped-xstocks)
* [xStocks API reference](https://docs.xstocks.fi/apis/openapi)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.