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.

• 1:1 Collateralized Tokens. 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. See Issuer Directory.
• Synthetic Perpetuals. 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). See Hyperliquid HIP-3 Markets.

⚠️ 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:

• Securities semantics. 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.
• Order lifecycle. 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.
• Two structural shapes. 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, 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

All surfaces share a single API key issued from the Yield.xyz dashboard.

Issuer Comparison

The canonical at-a-glance view of every StockKit issuer. Per-issuer detail lives in the Issuer Directory.

⚠️ 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.

Coverage overview

Mega-cap US Equities (Mag 7 & adjacent)

Other US Equities

US Broad-Market & Sector ETFs

International Equities

Commodities

Forex, Indices & Specialty

Forex.

Indices.

Specialty / crypto-adjacent.

Per-ticker mapping

Mega-cap US Equities (Mag 7 & adjacent)

Other US Equities

US Broad-Market & Sector ETFs

International Equities

Commodities

Forex, Indices & Specialty

Forex (HIP-3 only — no spot forex tokens on Dinari / Ondo / xStocks).

Indices.

Specialty / crypto-adjacent.

Issuer Directory

Hyperliquid HIP-3 Markets — Live

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.

Dinari — dShares

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.

ℹ️ 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 — 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

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.

ℹ️ 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 (Backed Finance / Kraken)

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.

ℹ️ 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 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.

1. Discover markets. 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).
2. Submit an action. 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.
3. Submit transactions. 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.).
4. Track positions. 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.

Identifying Instruments

Every StockKit market is returned by GET /v1/markets with the canonical shape:

{
  "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

All equity markets:

const equityMarkets = await fetch(
  "https://api.trade.yield.xyz/v1/markets?assetType=equity",
  { headers: { "x-api-key": YOUR_API_KEY } }
).then((r) => r.json());

Collateralized only (real share ownership):

const collateralized = markets.filter(
  (m) => m.structure === "collateralized"
);

Synthetic perps only:

const perps = markets.filter(
  (m) => m.structure === "synthetic_perp"
);

A specific underlying across all wrappers:

const nvdaAcrossIssuers = markets.filter(
  (m) => m.underlyingTicker === "NVDA"
);

💡 Tip

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. Dashboard setup & API key

1. Log in to dashboard.yield.xyz.
2. Navigate to Projects → Create Project.
3. Inside the project: API Keys → Create API Key.

ℹ️ Reference: Creating an API Key

2. Enable StockKit markets

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.

3. Discover markets and fetch metadata

List equity markets:

curl --request GET \
  --url 'https://api.trade.yield.xyz/v1/markets?providerId=hyperliquid-xyz&assetType=equity' \
  --header 'accept: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>'

Fetch NVDA perp metadata:

curl --request GET \
  --url 'https://api.trade.yield.xyz/v1/markets/hyperliquid-xyz-NVDA-perp' \
  --header 'accept: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>'

Metadata includes:

• markPrice (number) — current mark price for the perp.
• fundingRate (number) — current funding rate (annualized).
• openInterest (number) — notional open interest on the market.
• leverage (object) — { min, max, default } leverage bounds per market.
• fees (object) — maker / taker fees plus the builder-fee cap.
• requirements (object) — kycRequired, geoRestricted, and any project-level overrides.

4. Open a position

Open a 5× long NVDA perp position:

curl --request POST \
  --url https://api.trade.yield.xyz/v1/actions \
  --header 'content-type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{
    "marketId": "hyperliquid-xyz-NVDA-perp",
    "address": "<USER_WALLET_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:

✅ No client-side calldata construction is required. Sign each transaction in order and submit back via POST /v1/transactions/{transactionId}/submit.

5. Manage the position

Place a stop-loss and take-profit on the open position:

curl --request POST \
  --url https://api.trade.yield.xyz/v1/actions \
  --header 'content-type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{
    "marketId": "hyperliquid-xyz-NVDA-perp",
    "address": "<USER_WALLET_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.

6. Track positions, balances, and orders

curl --request POST \
  --url 'https://api.trade.yield.xyz/v1/positions' \
  --header 'content-type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{ "address": "<USER_WALLET_ADDRESS>" }'

Response surfaces:

• positions (array) — open positions: marketId, side, size, entryPrice, markPrice, unrealizedPnl, leverage, marginMode, liquidationPrice.
• balances (object) — USDC collateral by margin mode (isolated per market + cross-margin pool).
• orders (array) — 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

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.

curl --request POST \
  --url https://api.trade.yield.xyz/v1/actions \
  --header 'content-type: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --data '{
    "marketId": "hyperliquid-xyz-NVDA-perp",
    "address": "<USER_WALLET_ADDRESS>",
    "type": "approve_builder_fee",
    "arguments": {
      "builderAddress": "<YOUR_BUILDER_ADDRESS>",
      "feeTenthsOfBps": 100
    }
  }'

After approval, every subsequent order from this user includes {"b": "<YOUR_BUILDER_ADDRESS>", "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.

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.

💡 Tip

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

412 Precondition Failed — KYC required (collateralized issuers)

Returned for permissioned primary mints (Dinari, Ondo GM, xStocks via Backed) when the user address is not on the issuer's allowlist. Recoverable.

{
  "error": "PRECONDITION_FAILED",
  "message": "Address 0xabc… is not allowlisted for <issuer>",
  "details": {
    "address": "0xabc…",
    "issuer": "<issuer>",
    "kycUrl": "https://api.kyc.yield.xyz/v1/onboard?issuer=<issuer>&address=0xabc…"
  }
}

Action: redirect to details.kycUrl. Alternatively, route the user to a DEX-secondary path where available (Dinari dShares, xStocks).

422 Unprocessable Entity — leverage or size invalid

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.

409 Conflict — market closed / paused

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).

451 Unavailable for Legal Reasons — geo-restricted

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 to avoid surfacing restricted markets in the first place.

503 Service Unavailable — issuer upstream down

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:

{
  "error": "PRECONDITION_FAILED",
  "message": "Address 0xabc… is not allowlisted for <issuer>",
  "details": {
    "address": "0xabc…",
    "issuer": "<issuer>",
    "kycUrl": "https://api.kyc.yield.xyz/v1/onboard?issuer=<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 does not need to KYC again to buy Dinari equity dShares here — the KYC API tracks (wallet, issuer) pairs across both surfaces.

Choosing the Right Issuer for a Use Case

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.

• RWA Kit (Yield API) — 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.
• Allocator Vaults & OAVs — multi-issuer routing logic for blending equity, perp, and DeFi exposure.
• PerpsKit — 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

• API Reference — full Yield.xyz API specification: endpoints, schemas, response shapes across the Yield, Trade, KYC, Perps, and Borrow surfaces.
• RWA Kit (Yield API) — companion surface for yield-bearing RWAs (T-Bills, MMFs, fixed-income dShares, private credit, yield-bearing notes, basis/carry, yield-bearing stablecoins).
• PerpsKit — the broader perp surface: crypto perps via the existing Perps API; equity / commodity / forex / index perps via HIP-3 on the Trade API.
• KYC API — identity verification and allowlist enrolment, shared across Trade API and Yield API.
• Balances — balance lifecycle states and the per-market / batch balance endpoints.
• Creating an API Key — project setup and API key creation in the Yield.xyz dashboard.
• Geoblocking — region-based eligibility filtering aligned with issuer distribution policies.