Integration Guide ​

This guide distills the key practices that make Hub API integrations reliable and user-friendly. Cross-reference it with Getting Started and the API Reference for method details.

1. Centralise HubApi usage ​

Create a single HubApi instance for your app and expose thin helpers. This keeps permissions, behaviours, and error handling in one place.

// hub.ts
import HubApi, { CheckoutRequest, SignedTransaction } from '@nimiq/hub-api'

const hubApi = new HubApi('https://hub.nimiq.com')

export async function requestPayment(request: CheckoutRequest): Promise<SignedTransaction> {
  try {
    return await hubApi.checkout(request)
  } catch (error) {
    handleHubError(error as Error)
    throw error
  }
}

2. Call methods synchronously inside user actions ​

Browsers block popups opened outside direct interactions. Never await another promise before invoking a Hub method.

button.addEventListener('click', async () => {
  const result = await requestPayment({
    appName: 'My Shop',
    recipient: 'NQ07 0000 0000 0000 0000 0000 0000 0000 0000',
    value: 1_000, // 0.01 NIM
  })

  notifySuccess(result.hash)
})

3. Handle success and failure explicitly ​

Wrap calls in try/catch and branch on user cancellation versus genuine errors.

function handleHubError(error: Error) {
  if (error.message === 'Request was cancelled') 
    showToast('Action cancelled by the user')
  else if (error.message.includes('popup'))
    showToast('Enable popups or switch to redirect mode')
  else
    console.error(error)
    showToast('Hub request failed')
}

4. Manage UI state ​

• Disable the triggering button while the Hub popup is open.
• Surface progress indicators ("Waiting for confirmation…").
• For checkout results, forward the signed transaction to your backend immediately if you need server-side confirmations.

5. Use redirects for mobile or kiosk setups ​

Popups are convenient on desktop, but redirect flows avoid blocker dialogs on mobile. Instantiate the API with a redirect behaviour when needed:

const redirectBehavior = new HubApi.RedirectRequestBehavior(window.location.href, { orderId })
const hubApi = new HubApi('https://hub.nimiq.com', redirectBehavior)

hubApi.on(HubApi.RequestType.CHECKOUT, (result, state) => {
  completeOrder(state.orderId, result.hash)
})

hubApi.checkRedirectResponse()

6. Troubleshooting checklist ​

• Popup blocked: ensure the call happens synchronously in the event handler; fall back to redirects if necessary.
• Hub not loading: check network connectivity, CORS, and that no COOP/COEP headers are set.
• "Invalid request": verify addresses, units (Luna), and required fields before sending the request.
• Stale validity heights: fetch the latest block height from your RPC endpoint before calling signTransaction.

7. Testing strategy ​

• Point your app at https://hub.nimiq-testnet.com during development.
• Use the testnet faucet to obtain NIM for testing.
• Mock the Hub API in unit tests by stubbing the methods you use, returning realistic payloads.

8. Keep dependencies up to date ​

Pin Hub API versions in production (@nimiq/hub-api@1.10.0) and upgrade periodically to benefit from bug fixes. The package includes TypeScript definitions—leverage them to catch integration mistakes during development.

Further resources ​

• Quick Start
• Transactions Guide
• Cashlinks & Advanced Features
• Starter Template