Superstate API and developer tools: tokenized funds on Solana

Most Solana RWA write-ups stop at “there is a token.” Superstate is more interesting for builders because it ships a real HTTP surface + Solana programs + partner SDKs around permissioned tokenized funds and equities. The company (CEO Robert Leshner, Compound founder) positions itself as capital-markets infrastructure: tokenized funds (USTB, USCC, and third-party FundOS funds), Opening Bell for public equities on Ethereum and Solana, and transfer-agent style allowlisting.

This article is the developer map: what you can call without a key, how authenticated requests are signed, which APIs matter for ops and wallets, and how Solana Token-2022 + the Allowlist program actually work when you integrate DeFi or an onboarding flow.

Click to zoom

Product surface in one paragraph

USTB is the short-duration U.S. government securities fund (Invesco as investment manager in the current branding). USCC is the crypto carry fund (Bitwise management in the current branding). Both can live as book-entry or as on-chain shares; Solana is a first-class venue alongside Ethereum and Plume. Opening Bell tokenizes registered public shares (not synthetics) with compliance gates. FundOS is the platform for asset managers to run tokenized funds on Superstate infrastructure (Coinbase CUSHY is an example third-party fund path in the docs).

Eligibility, KYC, and investment agreements still gate access. The APIs below do not replace compliance; they automate fund data, portfolio ops, and partner onboarding once you are a Superstate partner or investor entity.

1. Public fund data API (no API key)

Superstate publishes fund fundamentals over https://api.superstate.com. Fund IDs from the docs:

USTB  → fund_id 1
USCC  → fund_id 2

Documented public-style endpoints (also listed in docs.superstate.com/investors/api; OpenAPI UI at swagger-ui):

# Daily NAV + AUM + outstanding shares (array of daily rows)
curl -sS "https://api.superstate.com/v1/funds/1/nav-daily"

# Yield (1d / 7d / 30d style fields)
curl -sS "https://api.superstate.com/v1/funds/1/yield"

# Holdings breakdown
curl -sS "https://api.superstate.com/v2/funds/1/holdings"

# Same paths with fund id 2 for USCC

Example shape for USTB NAV (live as of research; fields may grow):

{
  "fund_id": 1,
  "net_asset_value_date": "07/25/2026",
  "net_asset_value": "11.15534500",
  "assets_under_management": "826778499.7000",
  "outstanding_shares": "74115009.414769",
  "net_income_expenses": "75007.33910300"
}

Yield returns an as_of_date plus one_day / seven_day / thirty_day fractions (e.g. ~0.035 ≈ 3.5% annualized-style rates; interpret against Superstate’s fund docs, not as a trading oracle alone). Holdings returns a dated list of securities with cost, maturity, yield, and weight.

Builder use: dashboards, risk monitors, “show me Treasuries exposure” widgets, and agent tools that need audited-style fund series without scraping the marketing site.

2. Authenticated APIs: JWT vs API key

Docs describe two auth modes:

• JWT — log into the Superstate website session, then hit endpoints from Swagger while authenticated.
• API key pair — org/entity keys issued by Superstate (contact sales). Roles include at least TransactionViewer, FundManager, and OnboardingApi depending on endpoint.

HMAC request signing

Keyed requests are not a bare Bearer token. You must send:

Authorization: Bearer <api_key>
X-Nonce: <random UUID>
X-Timestamp: <epoch ms>
X-Params-Hash: SHA256(normalized path + sorted query)
X-Body-Hash: SHA256(body JSON)  // GET uses SHA256("{}")
X-Hmac: Base64(HMAC-SHA256(api_secret,
  api_key + nonce + timestamp + params_hash + body_hash))

Path normalization: leading slash, no trailing slash. Query keys sorted alphabetically (and by value if repeated), URL-encoded. Comma-separated filter values must not contain spaces or HMAC verification fails.

Official helper: @superstateinc/api-key-request (v0.1.x) with open source at superstateinc/request-with-api-key.

import {
  superstateApiKeyRequest,
  TransactionStatus,
} from "@superstateinc/api-key-request";

const transactions = await superstateApiKeyRequest({
  apiKey: process.env.SUPERSTATE_API_KEY!,
  apiSecret: process.env.SUPERSTATE_API_SECRET!,
  endpoint: "v2/transactions",
  method: "GET",
  queryParams: {
    transaction_status: TransactionStatus.Pending,
    transaction_type: "Purchase,Redeem", // no spaces after commas
  },
});

3. Transactions API

GET /v2/transactions (API key, TransactionViewer) returns TransactionV2 rows newest-first. Filters include status, type, time ranges, chain IDs, addresses, entity, and DIP market id.

Status: Pending | PaymentPending | Processed | Completed

Fund types include:
  Purchase, Redeem, Burn, ProtocolMint, ProtocolRedeem,
  MintRequest, UsdPurchase, UsdcPurchase, RedemptionRequest

General: OnchainTransfer, Tokenize, Bridge, ProtocolTransfer, AdminAdjustment
Equities: Issuance, Vest, Unlock, DipPurchase, OnchainDeFiLpIssuance, ...

Chain IDs (docs):
  1          Ethereum mainnet
  11155111   Sepolia
  98866/98867 Plume mainnet/testnet
  900        Solana MainnetBeta (internal Superstate id)
  901        Solana Devnet (internal Superstate id)

For completed on-chain fund subscriptions, docs say: look for operation_type: Purchase and status: Completed; use source_details.transaction_hash as the mint tx; share_amount is issued shares; dollar_amount is notional from price × shares. UsdPurchase / UsdcPurchase are temporary inbound payment rows, not completed subscriptions.

4. Balances API

GET /v1/balances (roles: FundManager or TransactionViewer) returns entity-scoped holdings with optional org rollups.

Balance labels:
  BookEntryAvailable   book-entry free to move
  BookEntryRestricted  restricted book-entry
  Token                on-chain tokenized shares
  Protocol             deposited in DeFi (Aave, Morpho, etc.)

Optional query: entity_id=<int>

Each instrument includes total_shares, optional notional and price, and a breakdown array with chain id, address nickname, and restrictive legend when present. This is the ops API for “what does this entity hold across book-entry vs Solana vs Ethereum?”

5. Onboarding API (wallets and partners)

For wallets, exchanges, and fintechs that already run KYC, the Onboarding API (OnboardingApi role) creates Superstate entities and allowlists wallets without forcing users through a full manual portal path for every address.

POST /v1/accounts/onboard/svm               # Solana create + allowlist
POST /v1/accounts/onboard/svm/mock          # dry-run test
POST /v1/accounts/onboard/svm/add-allowlist # extra Solana address
POST /v1/accounts/onboard/evm               # EVM create + allowlist
POST /v1/accounts/onboard/evm/mock
POST /v1/accounts/onboard/evm/add-allowlist
PUT  /v1/accounts/onboard/update            # partial entity update

Solana create request (simplified): version, optional userData KYC fields, walletAddress (base58), kycProvider (e.g. Sumsub), kycProviderId. Success returns entityId plus encodedTransaction: bincode then base64 of a partially signed Solana transaction the user must sign and broadcast to finish allowlisting.

Mock endpoints skip DB writes and return non-broadcastable txs (zero blockhash / expired signatures) so you can integrate without burning production allowlist slots. Only the partner that originally onboarded an entity can add more addresses or update that entity (403 otherwise).

6. Solana programs and Token-2022 design

From smart contracts docs, mainnet SVM addresses include:

Allowlist program:
  HFkKyweJDUuGer5KaCst5qZSYD5aapKaD7xzdNaoRtfA

USTB (Token-2022 mint):
  CCz3SGVziFeLYk2xfEstkiqJfYkjaSWb2GCABYsVcjo2

USCC (Token-2022 mint):
  BTRR3sj1Bn2ZjuemgbeQ6SCtf84iXS81CS7UDTSxUCaK

Burn address:
  2u8YwJTykTreziHBN5QwE7Bi2SyN8M2MicCscthtph9E

Pyth USTB oracle:
  EqggHKbjePzmXAX6MW3EsgjiJ4mhkbb8j5s5KfGs1gLq
Pyth USCC oracle:
  823Y4cV7XH2TzkB9NdHfTRoCKLrqXv8EgQP5nzEG43Hp

Token extensions used: Default Account State = Frozen, Permanent Delegate, Scaled UI Amount, Immutable Owner, Metadata / Metadata Pointer. The Allowlist program is the freeze authority. Accounts start frozen; a permissionless thaw instruction lets integrated DeFi protocols unfreeze for allowlisted users inside existing flows.

SDKs for the allowlist program:

• Rust: superstate-allowlist-interface
• TypeScript: @superstateinc/allowlist

Transfers only succeed between thawed / allowlisted accounts (Transfer / TransferChecked). Bridging and “burn to book-entry” that exist on EVM are not supported for SVM fund shares; the documented path is redeem + re-purchase targeting book-entry or another chain.

Note the split with Ethereum: atomic subscribe / redeem USDC paths and continuous price oracles are documented as Ethereum-only for USTB. On Solana, integrate via Token-2022 + allowlist + portal/API subscription flows and Pyth prices for DeFi, not the EVM subscribe helper.

7. How a Solana builder should approach Superstate

• Data only (public): wire NAV/yield/holdings for USTB and USCC into risk UIs and research bots. No key.
• Wallet / exchange partner: request OnboardingApi keys; implement Sumsub (or supported KYC) share tokens; complete SVM onboard by signing returned txs; track balances via Balances API.
• DeFi protocol: study Allowlist thaw + Token-2022 frozen default; use official allowlist SDKs; treat permissions as first-class (not optional). Confirm Superstate protocol allowlisting for your program addresses.
• Ops / fund admin: Transactions + Balances with HMAC client; filter by source_chain_id=900 for Solana mainnet activity in Superstate’s internal chain id scheme.

Superstate is not a general Solana RPC, not a stablecoin issuer, and not permissionless mint. It is compliant tokenized securities infrastructure with unusually complete APIs for a RWA issuer.

Resources

• superstate.com
• docs.superstate.com · llms.txt
• Fund data API · Swagger UI
• Transactions API · Balances API
• Onboarding API
• Smart contracts (EVM + SVM)
• @superstateinc/api-key-request · @superstateinc/allowlist · superstate-allowlist-interface
• github.com/superstateinc
• @SuperstateInc

If you are building Solana treasury, RWA collateral, or institutional wallet flows, Superstate is one of the few stacks where the fund economics API, partner onboarding, and Token-2022 allowlist model are documented enough to design against without reverse engineering a portal.