FAQ

Does the SDK work outside the HydraOne App Center?

Not on its own. The wallet lives in the host shell, so a game opened in a normal tab has nothing to connect to and init() rejects with ERR_NOT_IN_IFRAME. To run a game elsewhere, embed it in a page that uses @hydraone-sdk/host.

Do I need a backend?

Only for login. CIP-8 signatures must be verified and turned into a JWT by your own server. Wallet queries, signing and submitting need no backend of yours.

Does the SDK build transactions?

No. It asks the wallet to sign (signTx), submit (submitTx) and sign data (signData). Build transactions with a Cardano transaction library and pass the CBOR hex to the SDK.

Why does getBalance() return a list instead of a number?

The balance holds ADA and native assets. Use useWallet().balanceADA / useWalletBridgeClient().balanceADA, which read the lovelace for you, or sum the entries whose unit is lovelace.

Why are amounts bigint?

Lovelace values can exceed Number.MAX_SAFE_INTEGER once native assets and large balances are involved. The wallet hooks read the balance as a bigint so no precision is lost.

Is it safe to use in production with appCenterOrigin: '*'?

No, and the transport refuses it when env is production. Set the exact host origin.

Can I use it with server-side rendering?

Yes. Nothing touches window at import time. Create clients and call init() on the client only (inside useEffect, onMounted or a .client plugin). The React provider and Vue composables already do this.

In Vue and Nuxt with server rendering, register the createHydraOne plugin so every request gets its own client. See Vue and Nuxt.

Does it work with CommonJS?

Yes. The package ships ESM and CommonJS builds with matching types.

How big is it?

The root entry is about 23 KB gzipped, and each subpath is a separate entry. Run pnpm run size in the repository to see the current numbers.

Where is the API reference?

Generate it with pnpm run docs:api; it is written to packages/core/docs/api/.

Can more than one host embed my game?

Yes. Pass an array to appCenterOrigin, for example ['https://alpha.hydraone.app', 'https://staging.hydraone.app']. Messages are accepted from any listed origin, and replies are only ever sent to a listed origin. See Transports.

How do I report a bug or a vulnerability?

Bugs: open a GitHub issue. Vulnerabilities: use private reporting as described in SECURITY.md.

Next steps

• Troubleshooting when something does not work.
• Quick start to connect and sign your first transaction.