> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# StockKit
> Production-ready guide for integrating tokenized US equities, ETFs, commodities, forex, and indices — across 1:1 collateralized tokens and synthetic perpetuals — through the Yield.xyz Trade API.
## Overview
StockKit is the **Trade API surface** for on-chain stock, ETF, commodity, forex, and index exposure. It normalizes four structurally different ways of getting that exposure under a single market / action / portfolio interface — so integrators don't reimplement issuer-specific contracts, dividend models, or trade lifecycles.
The four issuers split into two structural categories. Internalize this split before reading anything else — it drives everything from dividend handling to KYC posture.
Each token represents one share of the underlying security, held at a regulated custodian. Discovery, trade, mint/redeem, positions, and the dividend stream (where one exists) all live here. Issuers: **Dinari dShares**, **Ondo Global Markets**, **Backed xStocks**.
Perpetual futures contracts that price-track the underlying. No share ownership, no dividends; 24/7 trading with leverage. Issuer: **Hyperliquid HIP-3** (the only StockKit issuer live on Yield.xyz today).
All four issuers expose the same StockKit lifecycle — discover markets, execute actions, track positions. Per-issuer quirks (dividend reinvestment vs cash payout, KYC posture, trading windows) are surfaced through the market metadata schema. See [Identifying Instruments](#identifying-instruments).
**Synthetic perps are not stock ownership.** HIP-3 markets deliver directional price exposure with leverage, but holders never own the share, never receive dividends, and never get voting rights. Make this distinction explicit in any UI that places HIP-3 markets next to Dinari / Ondo / xStocks listings.
***
## Why the Trade API
The Yield API was designed around staking, lending, LP, and other recurring-income shapes. Non-yield tokenized equities and synthetic perps introduce concerns that don't belong on that surface:
A tokenized AAPL share isn't "yield" — it's an equity claim with a price, corporate actions, voting rights, and shareholder communications. These need their own surface.
Stocks trade through order books with market hours, partial fills, stop-loss / take-profit logic — semantics the Yield API `enter / exit` model doesn't express.
Collateralized tokens and synthetic perps coexist on the same surface but require different normalization for positions, PnL, and risk reporting.
StockKit lives on the dedicated **Trade API** at `api.trade.yield.xyz`. KYC handoffs (where applicable) route through `api.kyc.yield.xyz` for PII isolation and regional residency — the same KYC API used by [RWA Kit](https://docs.yield.xyz/docs/rwakit), so a wallet that's KYC'd for Dinari fixed-income dShares via the Yield API is recognised when buying Dinari equity dShares here, and vice versa.
***
## API Surfaces
`https://api.trade.yield.xyz/v1` — market discovery, order placement, position tracking, corporate actions, voting (where supported). Equity / commodity / forex / index perps via Hyperliquid HIP-3 also served here.
`https://api.kyc.yield.xyz/v1` — identity verification, allowlist enrolment, region-segregated PII storage, issuer KYC handoffs. Shared across the Trade API and Yield API.
`https://api.yield.xyz/v1` — staking, lending, LP, DeFi, **and yield-bearing RWAs** (T-Bills, MMFs, fixed-income dShares, private credit, yield-bearing notes, basis/carry strategies, yield-bearing stablecoins). Equity dividends are not surfaced here — they're part of StockKit positions.
`https://perps.yield.xyz/v1` — crypto perpetual futures and the broader perps catalog. Remains live during the Trade API rollout; will eventually fold into Trade API.
All surfaces share a single API key issued from the [Yield.xyz dashboard](https://dashboard.yield.xyz/).
***
## Issuer Comparison
The canonical at-a-glance view of every StockKit issuer. Per-issuer detail lives in the [Issuer Directory](#issuer-directory).
| Issuer | Coverage | Structure | Networks | Trading window | Fees | KYC | Dividends | Voting | Fractional |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------- | ---------- |
| **Dinari** | 150+ US stocks; 100+ stocks & ETFs (incl. VanEck-listed `SLX.d`); commodities (`IAU`, `SIVR`); `ETHE` | 1:1 backed dShares; held in third-party brokerage | Ethereum, Base, Arbitrum, Avalanche (Dinari Financial Network) | Primary: US market hours. Secondary: 24/7 on DEXs | Flat + variable per-order fee; **5% standard distribution fee** on the dividend leg | Reg D KYC at primary mint/redeem; dShares freely transferable on secondary | | | |
| **Ondo Global Markets** | 260+ tokenized US stocks & ETFs (AAPL, TSLA, NVDA, SPY, QQQ, …) | 1:1 BVI SPV-backed token; underlying at US-registered broker-dealer; Ankura Trust as security agent | Ethereum, Solana, BNB Chain | 24/5 (Sun 8:05 PM ET → Fri 7:59 PM ET); tokens transferable 24/7 | Brokerage-style per-trade pricing (token-level fee + network gas)¹ | Required at primary; settled in `USDon` (1:1 USDC) | | | |
| **xStocks (Backed / Kraken)** | 131 total — 100 stocks + 27 ETFs + 4 specialist (TSLAx, NVDAx, AAPLx, SPYx, QQQx, GLDx)¹ | 1:1 collateralized tracker certificate; bankruptcy-remote; licensed custodians | **Solana (primary SPL), Ethereum, Mantle, TON, Ink** | Kraken Pro: 24/7 for top 10; rest 24/5. DEX secondary: 24/7 | Kraken: zero fees on USD/USDG xStock buys (promo¹). Primary mint/redeem with Backed: 0.20% issuance/redemption fee | Primary only (qualified investors via Backed); freely transferable on secondary | Not conferred | | |
| **Hyperliquid HIP-3** | 35+ equity / commodity / forex / index perps — NVDA, TSLA, AAPL, MSFT, AMZN, META, GOOGL, COIN, MSTR, HOOD, GOLD, SILVER, JPY, EUR, XYZ100 (Nasdaq 100), … | Synthetic perpetual futures (no share ownership) | HyperEVM | 24/7 — no market hours, no geographic restrictions | Maker / taker per market; HIP-3 user fees are **2× validator-operated baseline** (subject to Growth Mode discount, Q2 2026). Builder fees up to **0.1% (10 bps)** | Not enforced at issuer level; integrators apply their own geo/KYC rules | No dividend mechanism (synthetic exposure) | No share ownership | |
**HIP-3 deployer economics.** Deploying a HIP-3 market requires **staking 500,000 HYPE** (\~\$25M depending on price). **Growth Mode** (Q2 2026) can slash all-in HIP-3 user fees by up to 90% for selected markets and changes the `2×` validator-fee baseline materially. Confirm current per-market fees against the live order book before publishing rate cards.
***
## Asset-Type Index
Find an asset class. See every issuer that offers it and what wrapper they use.
| Ticker | Underlying | Dinari (`.d`) | Ondo GM (`on`) | xStocks (`x`) | Hyperliquid HIP-3 |
| ------ | ---------- | --------------------------------------------------- | -------------- | ------------- | ----------------- |
| AAPL | Apple | `AAPL.d` | `AAPLon` | `AAPLx` | `AAPL` |
| MSFT | Microsoft | `MSFT.d` | `MSFTon` | `MSFTx` | `MSFT` |
| NVDA | Nvidia | `NVDA.d` | `NVDAon` | `NVDAx` | `NVDA` |
| GOOGL | Alphabet | `GOOGL.d` | `GOOGLon` | `GOOGLx` | `GOOGL` |
| AMZN | Amazon | `AMZN.d` | `AMZNon` | `AMZNx` | `AMZN` |
| META | Meta | `META.d` | `METAon` | `METAx` | `META` |
| TSLA | Tesla | ✗ (use `MAGS.d` Mag-7 ETF or `TSLL.d` 2× leveraged) | `TSLAon` | `TSLAx` | `TSLA` |
| Ticker | Underlying | Dinari (`.d`) | Ondo GM (`on`) | xStocks (`x`) | Hyperliquid HIP-3 |
| ------ | ------------- | ------------- | -------------- | ------------- | ----------------- |
| NFLX | Netflix | ✗ | `NFLXon` | `NFLXx` | `NFLX` |
| AMD | AMD | `AMD.d` | `AMDon` | `AMDx` | `AMD` |
| INTC | Intel | `INTC.d` | `INTCon` | `INTCx` | `INTC` |
| MU | Micron | ✗ | `MUon` | `MUx` | `MU` |
| PLTR | Palantir | `PLTR.d` | `PLTRon` | `PLTRx` | `PLTR` |
| ORCL | Oracle | `ORCL.d` | `ORCLon` | `ORCLx` | `ORCL` |
| COIN | Coinbase | `COIN.d` | `COINon` | `COINx` | `COIN` |
| MSTR | MicroStrategy | `MSTR.d` | `MSTRon` | `MSTRx` | `MSTR` |
| HOOD | Robinhood | `HOOD.d` | `HOODon` | `HOODx` | `HOOD` |
| CRCL | Circle | ✗ | `CRCLon` | `CRCLx` | `CRCL` |
| RIVN | Rivian | ✗ | `RIVNon` | ✗ | `RIVN` |
| CRWV | CoreWeave | ✗ | `CRWVon` | ✗ | `CRWV` |
| SNDK | SanDisk | ✗ | `SNDKon` | `SNDKx` | `SNDK` |
| Product | Underlying | Dinari (`.d`) | Ondo GM (`on`) | xStocks (`x`) | Hyperliquid HIP-3 |
| ------- | --------------------------- | ------------- | -------------- | ------------- | -------------------------------- |
| SPY | S\&P 500 (SPDR) | `SPY.d` | `SPYon` | `SPYx` | ✗ (use `XYZ100` for Nasdaq) |
| QQQ | Nasdaq 100 (Invesco) | `QQQ.d` | `QQQon` | `QQQx` | `XYZ100` (Nasdaq 100 index perp) |
| VOO | S\&P 500 (Vanguard) | `VOO.d` | ✗ | ✗ | ✗ |
| IWM | Russell 2000 | `IWM.d` | ✗ | `IWMx` | ✗ |
| SMH | VanEck Semiconductors | `SMH.d` | ✗ | `SMHx` | ✗ |
| SLX | VanEck Steel ETF | `SLX.d` | ✗ | ✗ | ✗ |
| XOP | SPDR Oil & Gas Exploration | `XOP.d` | ✗ | `XOPx` | ✗ |
| URA | Global X Uranium ETF | `URA.d` | ✗ | `URAx` | ✗ (use `URNM` perp) |
| IAU | iShares Gold | `IAU.d` | ✗ | ✗ | ✗ (use `GOLD` perp) |
| GLD | SPDR Gold | `GLD.d` | ✗ | `GLDx` | ✗ (use `GOLD` perp) |
| SLV | iShares Silver | `SLV.d` | ✗ | `SLVx` | ✗ (use `SILVER` perp) |
| MAGS | Roundhill Magnificent Seven | `MAGS.d` | ✗ | ✗ | ✗ |
| Ticker | Underlying | Dinari (`.d`) | Ondo GM (`on`) | xStocks (`x`) | Hyperliquid HIP-3 |
| ------- | ------------ | ------------- | -------------- | ------------- | ----------------- |
| BABA | Alibaba | `BABA.d` | `BABAon` | ✗ | `BABA` |
| TSM | TSMC | `TSM.d` | `TSMon` | `TSMx` | `TSM` |
| ASML | ASML | `ASML.d` | `ASMLon` | `ASMLx` | ✗ |
| AZN | AstraZeneca | ✗ | ✗ | `AZNx` | ✗ |
| NVO | Novo Nordisk | `NVO.d` | ✗ | `NVOx` | ✗ |
| SONY | Sony | `SONY.d` | ✗ | ✗ | ✗ |
| SKHX | SK Hynix | ✗ | ✗ | ✗ | `SKHX` |
| SMSN | Samsung | ✗ | ✗ | ✗ | `SMSN` |
| HYUNDAI | Hyundai | ✗ | ✗ | ✗ | `HYUNDAI` |
| Asset | Dinari (physical ETF wrappers) | Ondo GM | xStocks (physical ETF wrappers) | Hyperliquid HIP-3 (synthetic perp) |
| ---------------------- | ------------------------------ | ------- | ---------------------------------- | ---------------------------------- |
| Gold (XAU) | `IAU.d`, `GLD.d` | ✗ | `GLDx`, `FGDLx` | `GOLD` |
| Silver (XAG) | `SIVR.d`, `SLV.d` | ✗ | `SLVx` | `SILVER` |
| Platinum | `PPLT.d` | ✗ | `PPLTx` | `PLATINUM` |
| Palladium | ✗ | ✗ | `PALLx` | ✗ |
| Copper (miners proxy) | ✗ | ✗ | `COPXx` (Global X Copper Miners) | `COPPER` (direct) |
| Crude Oil | `USO.d` (oil futures fund) | ✗ | `XOPx` (oil & gas exploration ETF) | `CL` (WTI) |
| Natural Gas | ✗ | ✗ | ✗ | `NATGAS` |
| Uranium (miners proxy) | `URA.d`, `URNJ.d` | ✗ | `URAx` | `URNM` |
**Forex (HIP-3 only — no spot forex tokens on Dinari / Ondo / xStocks).**
| Asset | Dinari | Ondo GM | xStocks | Hyperliquid HIP-3 |
| ----- | ------ | ------- | ------- | ----------------- |
| JPY | ✗ | ✗ | ✗ | `JPY` |
| EUR | ✗ | ✗ | ✗ | `EUR` |
**Indices.**
| Asset | Dinari (via ETF) | Ondo GM (via ETF) | xStocks (via ETF) | Hyperliquid HIP-3 (synthetic) |
| --------------------- | --------------------------- | ----------------- | ----------------- | ----------------------------- |
| S\&P 500 | `SPY.d`, `VOO.d` | `SPYon` | `SPYx` | ✗ |
| Nasdaq 100 | `QQQ.d`, `TQQQ.d` (3× bull) | `QQQon` | `QQQx`, `TQQQx` | `XYZ100` |
| Russell 2000 | `IWM.d` | ✗ | `IWMx` | ✗ |
| Dow Jones | `DIA.d` | ✗ | ✗ | ✗ |
| MSCI Emerging Markets | `EEM.d`, `VWO.d` | ✗ | `IEMGx`, `VXUSx` | ✗ |
**Specialty / crypto-adjacent.**
| Asset | Dinari | Ondo GM | xStocks | Hyperliquid HIP-3 |
| ----------------- | -------------------------------------------------- | -------- | --------------------------------- | -------------------- |
| Spot Bitcoin ETF | `IBIT.d`, `GBTC.d`, `FBTC.d`, plus 9 others | `IBITon` | ✗ | ✗ (use crypto perps) |
| Spot Ethereum ETF | `ETHA.d`, `ETHE.d` (Grayscale), `ETHU.d` (2× bull) | ✗ | ✗ | ✗ |
| Bitcoin miners | `MARA.d`, `RIOT.d`, `HUT.d`, `CORZ.d` | ✗ | `MARAx`, `RIOTx`, `HUTx`, `CORZx` | ✗ |
**Quick chooser.**
* **Real share with dividends and voting?** → Dinari.
* **Widest catalog with broker-dealer custody?** → Ondo Global Markets.
* **Most-liquid secondary on Solana DEXs?** → xStocks.
* **24/7 leveraged exposure with no off-chain settlement?** → Hyperliquid HIP-3.
***
## Issuer Directory
Hyperliquid's **HIP-3** enables permissionless builder-deployed perpetual markets on top of HyperCore — including 35+ equity, commodity, forex, and index perps. Unlike the three collateralized issuers, HIP-3 markets are **synthetic perpetual futures**: users get directional price exposure with up to 20× leverage, but never own the underlying share. Trading is 24/7, settlement is on-chain in USDC, and there are no market hours or geographic gating at the protocol level.
Hyperliquid is the only StockKit issuer that is **live on Yield.xyz today**. The remaining three are upcoming.
| Detail | Value |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Coverage breadth | 35+ markets — equities, commodities, forex, indices |
| Example equity markets | NVDA, GOOGL, TSLA, MSFT, AAPL, AMZN, META, NFLX, AMD, INTC, MU, TSM, PLTR, ORCL, BABA, COIN, MSTR, HOOD, RIVN, CRWV, CRCL, SNDK, SKHX, SMSN, HYUNDAI, URNM |
| Commodity markets | GOLD, SILVER, COPPER, PLATINUM, CL (Crude Oil WTI), NATGAS |
| Forex markets | JPY, EUR |
| Index markets | XYZ100 (Nasdaq 100) |
| Network | HyperEVM (Hyperliquid L1) |
| Structure | Synthetic perpetual futures (no share ownership) |
| Trading hours | 24/7 |
| Collateral | USDC |
| Leverage | Up to 20× (configurable per market) |
| Margin modes | Isolated, cross |
| Order types | Market, limit; stop-loss / take-profit |
| Fees (user) | Maker / taker per market; HIP-3 user fees are **2× the equivalent validator-operated perp** baseline |
| Deployer stake | **500,000 HYPE** to deploy a HIP-3 market |
| Builder-fee cap | **0.1% (10 bps)** of notional, per fill |
| Builder-fee approval | Via `ApproveBuilderFee` action; subsequent orders include `{"b": address, "f": tenths_of_bps}` |
| Dividends | None (no dividend mechanism) |
| KYC | Not enforced at protocol level — integrators apply their own geo/KYC rules. See [Geoblocking](https://docs.yield.xyz/docs/geoblocking) |
**Growth Mode (Q2 2026).** Hyperliquid's Growth Mode can slash all-in HIP-3 user fees by up to 90% for participating markets, and the builder-fee share range narrows to 0–100% (vs 0–300% baseline). Confirm whether Growth Mode applies to each market you surface before publishing rate cards.
Dinari issues **dShares** — ERC-20 wrappers that track underlying US-listed equities, ETFs, commodities, and bonds **1:1**. Each token is fully backed by the underlying security held in a third-party brokerage account, and **holders retain shareholder rights including dividends and corporate actions**. Primary mint and redemption are KYC-gated under SEC Reg D; once issued, dShares are freely transferable as standard ERC-20s.
| Detail | Value |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Coverage breadth | 150+ US securities — equities, ETFs, commodities, bonds, ETHE |
| Example tickers | `AAPL.d`, `TSLA.d`, `NVDA.d`, `SPY.d`, `GOOGL.d`, `META.d`, `MSTR.d`, `SLX.d`, `IAU.d`, `SIVR.d`, `ETHE.d` |
| Networks | Ethereum, Base, Arbitrum, Avalanche (via Dinari Financial Network) |
| Structure | 1:1 backed; held in third-party brokerage |
| Regulatory wrapper | SEC Reg D exemption |
| Primary mint / redeem | KYC + KYB at Dinari's portal (handoff via [KYC API](https://api.kyc.yield.xyz/v1)) |
| Secondary trading | Permissionless ERC-20 on DEXs |
| Trading window | Primary: US equity market hours. Secondary: 24/7 on DEXs |
| Fees | `fee_buy = fee_flat + fee_variable × x_paid`; `fee_sell = fee_flat + fee_variable × (x_proceeds − fee_flat)`; 5% standard dividend fee |
| Dividends | Paid through to token holders (net of 5% fee). Surfaced here via the position dividend feed (`Position.distributions[]`) under `distributionMode = "off_chain_account_credit"` |
| Corporate actions | Honored (splits, mergers, etc.) |
| Shareholder voting | Retained |
| Partner-fee passthrough | Configurable per project — see [Setting up discretionary fees](https://docs.yield.xyz/docs/setting-up-discretionary-fees) |
| Fractional shares | Yes |
**Cross-reference.** Dinari spans two surfaces:
* \*\*Trade API \*\*— every Dinari equity dShare: single-name stocks (dividend-paying and non-dividend), equity ETFs (`SPY.d`, `IAU.d`, `SIVR.d`, `SLX.d`, `ETHE.d`). Discovery, mint / redeem, secondary swap, transfer, positions, and the dividend feed for dividend-paying shares.
* [**Yield API / RWA Kit**](https://docs.yield.xyz/docs/rwakit) — Dinari's fixed-income dShares (`USFR.d`, `FBND.d`, `CLOA.d`, …, 13 total) and the `USD+` yield-bearing stablecoin.
Both surfaces share the same KYC API, so one Dinari Account link applies across both.
Ondo Global Markets issues tokenized US stocks and ETFs through a BVI-incorporated SPV, backed 1:1 by securities held at US-registered broker-dealers, with **Ankura Trust as independent security agent**. With 260+ NYSE and NASDAQ-listed assets and live deployments on three major networks, Ondo GM is the largest tokenized equity issuer by TVL — surpassing **\$1B in TVL** inside its first eight months and holding **\~70% of the tokenized stock market** by share as of May 2026.
| Detail | Value |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| Coverage breadth | 260+ US stocks & ETFs |
| Example tickers | `ondoAAPL`, `ondoTSLA`, `ondoNVDA`, `ondoGOOGL`, `ondoSPY`, `ondoQQQ` |
| Networks | Ethereum, Solana, BNB Chain |
| Structure | BVI SPV; underlying held at US-registered broker-dealer; Ankura Trust as independent security agent |
| Regulatory approval | Approved across 30 EU/EEA countries (500M+ eligible investors) |
| Settlement asset | `USDon` — atomically converted 1:1 with USDC on mint/redeem |
| Trading window | 24/5 (Sun 8:05 PM ET → Fri 7:59 PM ET); tokens transferable 24/7 |
| Mint / redeem | USDC → atomic conversion to `USDon` → token mint. Reverse on redeem |
| Fees | Brokerage-style per-trade pricing — verify schedule with Ondo for partner integrations |
| Dividends | Passed through to token holders |
| Corporate actions | Honored |
| Voting | Broadridge proxy-voting integration announced 27 Apr 2026 |
| KYC | Required at primary — handoff via [KYC API](https://api.kyc.yield.xyz/v1) |
| Partner-fee passthrough | Configurable per project |
| Fractional shares | Yes |
| Market share | \~70% of tokenized stock market by share; \$1B+ TVL as of May 2026 |
**Why `USDon`.** Routing settlement through Ondo's `USDon` stablecoin keeps the cash leg fully on-chain and isolates it from broker-dealer settlement timing. From the integrator's perspective, this is transparent — users deposit USDC and receive the tokenized equity in the same transaction.
xStocks are the leading tokenized equity standard by trading volume. Each xStock is a **1:1 collateralized tracker certificate** issued under Switzerland's DLT Act and held with licensed custodians in bankruptcy-remote structures. Backed Finance, the issuer, was acquired by Kraken in December 2025 — unifying issuance, trading, and settlement under one roof. xStocks are permissionless post-issuance.
| Detail | Value |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| Coverage breadth | 131 total — 100 stocks + 27 ETFs + 4 specialist assets¹ |
| Top-10 24/7 markets | `TSLAx`, `QQQx`, `SPYx`, `NVDAx`, `CRCLx`, `AAPLx`, `HOODx`, `MSTRx`, `GLDx`, `GOOGLx` |
| Networks | **Solana (primary SPL), Ethereum, Mantle, TON, Ink** |
| Structure | 1:1 tracker certificate; bankruptcy-remote; licensed custodians |
| Regulatory wrapper | Switzerland DLT Act |
| Primary mint / redeem | KYC required for qualified investors via Backed — handoff via [KYC API](https://api.kyc.yield.xyz/v1) |
| Primary fee | 0.20% issuance / redemption |
| Secondary trading | Permissionless on Solana / Ethereum / Mantle / TON / Ink DEXs; also on Kraken Pro (regulated venue) |
| Kraken trading | Zero fees on xStock USD/USDG buys (promotional¹); 24/7 for top 10, 24/5 for rest |
| Dividends | Auto-reinvested into more of the same token (no cash payout). Token balance increases to reflect dividend |
| Shareholder voting | Not conferred |
| Corporate actions | Handled by issuer (splits, etc.) |
| Partner-fee passthrough | Configurable on secondary |
| Fractional shares | Yes |
**Backed's bToken trackers live on the Yield API.** Backed also issues short-duration fixed-income trackers (`bIB01`, `bC3M`) that are yield-bearing rather than equity. Those are served via [RWA Kit](https://yieldxyz.mintlify.app/documentation/kits/rwa-kit) on `api.yield.xyz`, not here. xStocks (`TSLAx`, etc.) and `bCSPX` (the S\&P 500 UCITS tracker) are equity-style and live on the Trade API.
**Why xStocks sit in both buckets.** Backed's primary issuance is permissioned, but every issued xStock is a freely transferable SPL / ERC-20 token on secondary. Most end-user flows route through DEX swap or Kraken Pro, not primary mint with Backed.
***
## The Integration Model
Every StockKit market — collateralized or synthetic — follows the same four-phase lifecycle.
Call `GET /v1/markets` to enumerate enabled markets for your project. Filter on `providerId`, `assetType` (`equity` / `etf` / `commodity` / `forex` / `index`), `network`, or `structure` (`collateralized` / `synthetic_perp`).
Call `POST /v1/actions` with a market ID, user address, and the action payload (open / close / limit / stop-loss / take-profit, or mint / redeem / swap for collateralized issuers). The Trade API returns one or more **fully constructed unsigned transactions** plus an `actionId` for status polling.
Sign each transaction via your custody infrastructure and submit it back through `POST /v1/transactions/{transactionId}/submit`. The transaction is broadcast on the appropriate network (HyperEVM, Ethereum, Solana, Base, etc.).
Poll `POST /v1/positions`, `/v1/balances`, and `/v1/orders` for per-user state. Use `GET /v1/actions/{actionId}` for action progress (signed → broadcast → confirmed).
For KYC-gated issuers (Dinari primary mint, Ondo GM primary, xStocks primary), `actions` returns a recoverable **HTTP 412** if the address is not yet KYC'd. See [KYC Precondition Errors](#kyc-precondition-errors).
***
## Identifying Instruments
Every StockKit market is returned by `GET /v1/markets` with the canonical shape:
```json theme={null}
{
"id": "hyperliquid-xyz-NVDA-perp",
"providerId": "hyperliquid-xyz",
"issuer": "hyperliquid",
"structure": "synthetic_perp",
"assetType": "equity",
"underlyingTicker": "NVDA",
"network": "hyperevm",
"tradingHours": "24/7",
"settlementAsset": "USDC",
"leverage": { "min": 1, "max": 20, "default": 5 },
"marginModes": ["isolated", "cross"],
"orderTypes": ["market", "limit", "stop_loss", "take_profit"],
"fees": {
"maker": { "bps": 2 },
"taker": { "bps": 4 },
"builderFeeCapBps": 10
},
"requirements": {
"kycRequired": false,
"geoRestricted": false
}
}
```
### Filter Assets
```typescript All equity markets theme={null}
const equityMarkets = await fetch(
"https://api.trade.yield.xyz/v1/markets?assetType=equity",
{ headers: { "x-api-key": YOUR_API_KEY } }
).then((r) => r.json());
```
```typescript Collateralized only (real share ownership) theme={null}
const collateralized = markets.filter(
(m) => m.structure === "collateralized"
);
```
```typescript Synthetic perps only theme={null}
const perps = markets.filter(
(m) => m.structure === "synthetic_perp"
);
```
```typescript A specific underlying across all wrappers theme={null}
const nvdaAcrossIssuers = markets.filter(
(m) => m.underlyingTicker === "NVDA"
);
```
When surfacing a single underlying across multiple wrappers (e.g. NVDA via Dinari, Ondo GM, xStocks, and Hyperliquid HIP-3), use the `structure` field to drive UI grouping. Collateralized tokens belong in a "Buy & hold" surface; synthetic perps belong in a "Trade with leverage" surface. Mixing them silently confuses end users.
***
## Integration Walkthrough — Hyperliquid HIP-3 (Live)
The Trade API contract is identical for every StockKit market. We use **Hyperliquid HIP-3 NVDA** as the example because it's the only live integration today, and it exercises the full action / transaction / position surface.
1. Log in to [`dashboard.yield.xyz`](https://dashboard.yield.xyz/).
2. Navigate to **Projects → Create Project**.
3. Inside the project: **API Keys → Create API Key**.
Reference: [Creating an API Key](https://docs.yield.xyz/docs/creating-an-api-key)
By default, **no markets are enabled** in a new project.
1. In your project, scroll to the **StockKit** section.
2. Open the **Hyperliquid HIP-3** category.
3. Search for and select the markets you want enabled (e.g. NVDA, TSLA, GOLD, XYZ100).
4. Click **Save**.
Only enabled markets will be returned by `GET /v1/markets` for this project's API key.
```bash List equity markets theme={null}
curl --request GET \
--url 'https://api.trade.yield.xyz/v1/markets?providerId=hyperliquid-xyz&assetType=equity' \
--header 'accept: application/json' \
--header 'x-api-key: '
```
```bash Fetch NVDA perp metadata theme={null}
curl --request GET \
--url 'https://api.trade.yield.xyz/v1/markets/hyperliquid-xyz-NVDA-perp' \
--header 'accept: application/json' \
--header 'x-api-key: '
```
Metadata includes:
Current mark price for the perp.
Current funding rate (annualized).
Notional open interest on the market.
`{ min, max, default }` — leverage bounds per market.
Maker / taker fees plus the builder-fee cap.
`kycRequired`, `geoRestricted`, and any project-level overrides.
Open a 5× long NVDA perp position.
```bash theme={null}
curl --request POST \
--url https://api.trade.yield.xyz/v1/actions \
--header 'content-type: application/json' \
--header 'x-api-key: ' \
--data '{
"marketId": "hyperliquid-xyz-NVDA-perp",
"address": "",
"type": "open_position",
"arguments": {
"side": "long",
"size": "100",
"leverage": 5,
"orderType": "market",
"marginMode": "isolated"
}
}'
```
The response contains one or more **fully constructed unsigned transactions**:
| Step | Transaction | What happens |
| ---- | --------------------------------------- | ------------------------------------------------------------- |
| 0 | `APPROVE_BUILDER_FEE` (first-time only) | Approves the builder code for this user wallet on Hyperliquid |
| 1 | `OPEN_POSITION` | Submits the market order to the Hyperliquid order book |
No client-side calldata construction is required. Sign each transaction in order and submit back via `POST /v1/transactions/{transactionId}/submit`.
Place a stop-loss and take-profit on the open position.
```bash theme={null}
curl --request POST \
--url https://api.trade.yield.xyz/v1/actions \
--header 'content-type: application/json' \
--header 'x-api-key: ' \
--data '{
"marketId": "hyperliquid-xyz-NVDA-perp",
"address": "",
"type": "set_stop_loss",
"arguments": { "triggerPrice": "120.00" }
}'
```
Supported action types: `open_position`, `close_position`, `partial_close`, `place_limit_order`, `cancel_order`, `set_stop_loss`, `set_take_profit`, `update_leverage`, `change_margin_mode`.
```bash theme={null}
curl --request POST \
--url 'https://api.trade.yield.xyz/v1/positions' \
--header 'content-type: application/json' \
--header 'x-api-key: ' \
--data '{ "address": "" }'
```
Response surfaces:
Open positions: `marketId`, `side`, `size`, `entryPrice`, `markPrice`, `unrealizedPnl`, `leverage`, `marginMode`, `liquidationPrice`.
USDC collateral by margin mode (isolated per market + cross-margin pool).
Open limit orders, stop-loss / take-profit triggers, pending cancellations.
For multi-market, multi-address portfolio views, use the batch endpoints (`/v1/positions`, `/v1/balances`, `/v1/orders` all accept an array of addresses).
Reference: [Balances](https://docs.yield.xyz/docs/balances)
### Builder-fee monetization
HIP-3 markets support **builder-code monetization**: a per-fill fee up to 10 bps (0.1%) on notional, routed to a project-owned wallet.
```bash theme={null}
curl --request POST \
--url https://api.trade.yield.xyz/v1/actions \
--header 'content-type: application/json' \
--header 'x-api-key: ' \
--data '{
"marketId": "hyperliquid-xyz-NVDA-perp",
"address": "",
"type": "approve_builder_fee",
"arguments": {
"builderAddress": "",
"feeTenthsOfBps": 100
}
}'
```
After approval, every subsequent order from this user includes `{"b": "", "f": 100}` in the payload and the builder receives the fee on each fill.
**Growth Mode caveat.** Under Hyperliquid's Growth Mode (Q2 2026), the builder-fee share range narrows from 0–300% to **0–100%**. Confirm your builder-fee economics against the live deployer configuration before publishing rate cards.
***
## Position Lifecycle & Balance States
StockKit normalizes every position into one of five states, regardless of issuer or structure.
| State | Meaning | When it surfaces |
| ------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `Active` | Position open and marked-to-market (perps) or token held and accruing dividends (collateralized) | After successful action submission and confirmation |
| `Pending` | Action submitted but not yet confirmed on-chain; or off-chain mint/redeem in flight | While the transaction is being broadcast / confirmed, or while Ondo GM / Dinari processes a primary mint |
| `Closing` | Close or partial-close action submitted; perp position being unwound | Mid-close on perps; mid-redeem on collateralized tokens |
| `Closed` | Position fully closed; final PnL realized to USDC (perps) or token redeemed to USDC (collateralized) | After all fills settle |
| `Liquidated` | Perp position auto-closed by the protocol after hitting the liquidation price | HIP-3 markets only |
The dividend feed for Dinari and Ondo GM (`Position.distributions[]`) is independent of state — distributions can accrue against an `Active` position regardless of issuer. Pull historical declarations via `GET /v1/markets/{marketId}/distributions` and per-user paid events via `GET /v1/positions/{userId}/{marketId}/distributions`.
For **portfolio reporting**, treat `Pending` and `Closing` as still allocated — they are in-flight cash flows, not realized exits. `Liquidated` is a realized exit but warrants a distinct UI treatment from a user-initiated `Closed`.
***
## Error Handling Reference
Returned for permissioned primary mints (Dinari, Ondo GM, xStocks via Backed) when the user address is not on the issuer's allowlist. Recoverable.
```json theme={null}
{
"error": "PRECONDITION_FAILED",
"message": "Address 0xabc… is not allowlisted for ",
"details": {
"address": "0xabc…",
"issuer": "",
"kycUrl": "https://api.kyc.yield.xyz/v1/onboard?issuer=&address=0xabc…"
}
}
```
**Action:** redirect to `details.kycUrl`. Alternatively, route the user to a DEX-secondary path where available (Dinari dShares, xStocks).
Returned for HIP-3 actions when the requested leverage is outside the market's `[min, max]` range, or when the requested size violates margin requirements.
**Action:** surface `market.leverage` and `market.minSize` to the user before request submission.
Returned when an action is attempted on a collateralized market outside its trading window (e.g. Ondo GM during the 24/5 weekend window) or on a HIP-3 market the deployer has paused.
**Action:** poll `GET /v1/markets/{id}` until `status.tradingOpen` returns to `true`, or route the user to a 24/7 alternative (Hyperliquid HIP-3 for the same underlying, where one exists).
Returned when the request originates from a region the issuer does not serve (e.g. US persons accessing Backed xStocks via primary).
**Action:** apply geo-aware filtering at the project layer using [Geoblocking](https://docs.yield.xyz/docs/geoblocking) to avoid surfacing restricted markets in the first place.
Returned when the issuer's primary API is unreachable, or when Hyperliquid's order-book API is degraded.
**Action:** retry with backoff. For collateralized issuers, the secondary DEX path remains available when primary is degraded.
### KYC Precondition Errors
When a user attempts a permissioned primary action from a non-allowlisted address, the API returns **HTTP 412 Precondition Failed**:
```json theme={null}
{
"error": "PRECONDITION_FAILED",
"message": "Address 0xabc… is not allowlisted for ",
"details": {
"address": "0xabc…",
"issuer": "",
"kycUrl": "https://api.kyc.yield.xyz/v1/onboard?issuer=&address=0xabc…"
}
}
```
Recommended UX:
1. Catch the 412.
2. Redirect to `details.kycUrl` (a hosted flow on `api.kyc.yield.xyz` that proxies to the issuer's portal).
3. After KYC confirmation, retry the original action.
For Dinari and xStocks, you can alternatively route the user to a DEX secondary swap path — no KYC required, instant settlement, but subject to DEX liquidity.
**KYC is shared across Trade API and Yield API.** A wallet that's already KYC'd for Dinari's fixed-income line (USFR.d, etc.) via [RWA Kit](https://docs.yield.xyz/docs/rwakit) does not need to KYC again to buy Dinari equity dShares here — the [KYC API](https://api.kyc.yield.xyz/v1) tracks `(wallet, issuer)` pairs across both surfaces.
***
## Choosing the Right Issuer for a Use Case
| If your user wants… | Recommend… | Why |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Real ownership of a US stock with dividends and voting | **Dinari** | Only issuer that retains full shareholder rights |
| Broadest catalog with broker-dealer-grade custody | **Ondo Global Markets** | 260+ assets across the three biggest networks; \~70% market share |
| Most-liquid secondary trading on Solana DEXs | **xStocks** | Leading TVL on SPL deployments |
| 24/7 directional trading with leverage and no off-chain settlement | **Hyperliquid HIP-3** | Synthetic perps, USDC-settled, instant |
| Tokenized exposure to commodities or forex | **Hyperliquid HIP-3** (broadest) or **Dinari** (commodity ETFs like `IAU.d`) | Different wrappers — perp vs. backed ETF |
| EU retail availability under MiCA | **Ondo Global Markets** | Approved across 30 EU/EEA countries |
| US Reg D distribution | **Dinari** | Native Reg D structure |
***
## Vault & Portfolio Compatibility
All four issuers report positions through the same Trade API interface, so equity exposure appears alongside perps and DeFi positions in a **unified portfolio view**. Where vault constructs apply (e.g. an equity-yield Optimized Allocator Vault blending dShare dividend strategies with on-chain yield), the routing engine resolves issuer-specific KYC handoffs per leg via the [KYC API](https://api.kyc.yield.xyz/v1).
For cash-yielding RWA strategies (T-Bills, MMFs, private credit, fixed-income dShares, yield-bearing notes, basis/carry, yield-bearing stablecoins). Equity dividends live here in StockKit, not in RWA Kit.
Multi-issuer routing logic for blending equity, perp, and DeFi exposure.
The broader perp surface that HIP-3 sits inside — crypto perps via the existing Perps API, equity / commodity / forex / index perps via HIP-3 on the Trade API.
***
## Resources
Full Yield.xyz API specification — endpoints, schemas, response shapes across the Yield, Trade, KYC, Perps, and Borrow surfaces.
Companion surface for yield-bearing RWAs (T-Bills, MMFs, fixed-income dShares, private credit, yield-bearing notes, basis/carry, yield-bearing stablecoins).
The broader perp surface — crypto perps via the existing Perps API; equity / commodity / forex / index perps via HIP-3 on the Trade API.
Identity verification and allowlist enrolment, shared across Trade API and Yield API.
Balance lifecycle states and the per-market / batch balance endpoints.
Project setup and API key creation in the Yield.xyz dashboard.
Region-based eligibility filtering aligned with issuer distribution policies.