StockKit - Yield.xyz

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.

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

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.

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

Trade API

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.

KYC API

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.

Yield API (RWAKit lives here)

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.

Perps API (existing)

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.

Issuer Comparison

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

Issuer	Coverage	Structure	Networks	Trading window	Fees	KYC	Dividends	Voting
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 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.

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

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

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

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

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

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

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.

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

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

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

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

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

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.

Dashboard setup & API key

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

Reference: Creating an API Key

Enable StockKit markets

By default, no markets are enabled in a new project.

In your project, scroll to the StockKit section.
Open the Hyperliquid HIP-3 category.
Search for and select the markets you want enabled (e.g. NVDA, TSLA, GOLD, XYZ100).
Click Save.

Only enabled markets will be returned by GET /v1/markets for this project’s API key.

Discover markets and fetch metadata

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>'

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:

number

Current mark price for the perp.

number

Current funding rate (annualized).

number

Notional open interest on the market.

object

{ min, max, default } — leverage bounds per market.

object

Maker / taker fees plus the builder-fee cap.

object

kycRequired, geoRestricted, and any project-level overrides.

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:

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.

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.

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:

array

Open positions: marketId, side, size, entryPrice, markPrice, unrealizedPnl, leverage, marginMode, liquidationPrice.

object

USDC collateral by margin mode (isolated per market + cross-margin pool).

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.

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

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:

Catch the 412.
Redirect to details.kycUrl (a hosted flow on api.kyc.yield.xyz that proxies to the issuer’s portal).
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

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.

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.

​Overview

1:1 Collateralized Tokens

Synthetic Perpetuals

​Why the Trade API

Securities semantics

Order lifecycle

Two structural shapes

​API Surfaces

Trade API

KYC API

Yield API (RWAKit lives here)

Perps API (existing)

​Issuer Comparison

​Asset-Type Index

​Issuer Directory

​The Integration Model

​Identifying Instruments

​Filter Assets

​Integration Walkthrough — Hyperliquid HIP-3 (Live)

​Builder-fee monetization

​Position Lifecycle & Balance States

​Error Handling Reference

​KYC Precondition Errors

​Choosing the Right Issuer for a Use Case

​Vault & Portfolio Compatibility

RWA Kit (Yield API)

Allocator Vaults & OAVs

PerpsKit

​Resources

API Reference

RWA Kit (Yield API)

PerpsKit

KYC API

Balances

Creating an API Key

Geoblocking

Overview

Why the Trade API

API Surfaces

Issuer Comparison

Asset-Type Index

Issuer Directory

The Integration Model

Identifying Instruments

Filter Assets

Integration Walkthrough — Hyperliquid HIP-3 (Live)

Builder-fee monetization

Position Lifecycle & Balance States

Error Handling Reference

KYC Precondition Errors

Choosing the Right Issuer for a Use Case

Vault & Portfolio Compatibility

Resources