---
title: "Advanced Features"
description: "Cashlinks, privileged swap helpers, and multi-chain considerations"
canonical_url: "https://nimiq.dev/hub/guide/advanced"
---
# Advanced Features

> Cashlinks, privileged swap helpers, and multi-chain considerations

Most third-party integrations focus on `checkout`, `signTransaction`, and `signMessage`. This page covers the extra
functionality available through the Hub API and clarifies which features require privileged access.

## Cashlinks

Cashlinks are shareable links that contain claimable value. Anyone with the link can redeem the funds via the Hub. The
API exposes two public methods for working with cashlinks: `createCashlink()` and `manageCashlink()`.

### Creating a Cashlink

<code-group>

```ts [create-cashlink.ts]
const cashlink = await hubApi.createCashlink({
  appName: 'Promo Campaign',
  value: 50_000, // 0.5 NIM (value is optional, defaults to user input)
  message: 'Thanks for trying our app!',
  theme: HubApi.CashlinkTheme.GENERIC,
  returnLink: true, // Show the result screen inside your app
  skipSharing: true, // Skip Hub sharing UI when returnLink is true
})

console.log('Share this URL:', cashlink.link)
```

</code-group>

`CreateCashlinkRequest` extends `BasicRequest` and supports these options:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        value
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Amount in Luna; omit to let the user enter an amount.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Optional greeting shown to the recipient. Use <code>
        autoTruncateMessage
      </code>
      
       if you plan to send long text.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        theme
      </code>
    </td>
    
    <td>
      <code>
        HubApi.CashlinkTheme
      </code>
    </td>
    
    <td>
      Controls the look of the Hub UI.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        senderAddress
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Prefill the funding address when you know which account should pay.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        senderBalance
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Optional balance hint for Hub optimisations.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fiatCurrency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ISO 4217 code used for contextual pricing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        returnLink
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      When <code>
        true
      </code>
      
      , the Hub redirects back to your app. Combine with <code>
        skipSharing
      </code>
      
       to bypass the share dialog.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skipSharing
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Only valid when <code>
        returnLink
      </code>
      
       is <code>
        true
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoTruncateMessage
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Automatically shortens long messages.
    </td>
  </tr>
</tbody>
</table>

### Managing a Cashlink

<code-group>

```ts [manage-cashlink.ts]
const cashlink = await hubApi.manageCashlink({
  appName: 'Promo Campaign',
  cashlinkAddress: 'NQ30 F0O ...',
})

if (cashlink.status === HubApi.CashlinkState.UNCLAIMED) {
  console.log('Cashlink still unclaimed — you may cancel it inside the Hub UI.')
}
```

</code-group>

### Result Format

```ts
interface Cashlink {
  address: string
  message: string
  value: number
  status: HubApi.CashlinkState
  theme: HubApi.CashlinkTheme
  link?: string
}
```

`HubApi.CashlinkState` enumerates the lifecycle:

<table>
<thead>
  <tr>
    <th>
      State
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        UNKNOWN
      </code>
    </td>
    
    <td>
      Cashlink status could not be determined.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        UNCHARGED
      </code>
    </td>
    
    <td>
      Awaiting funding.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CHARGING
      </code>
    </td>
    
    <td>
      Funding transaction in flight.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        UNCLAIMED
      </code>
    </td>
    
    <td>
      Ready to be claimed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLAIMING
      </code>
    </td>
    
    <td>
      Claim transaction in flight.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLAIMED
      </code>
    </td>
    
    <td>
      Funds redeemed.
    </td>
  </tr>
</tbody>
</table>

### Tips

- Pin cashlink values in Luna to avoid floating-point rounding issues.
- Provide context (e.g. campaign or customer) using the `returnLink` state object when you call
`new HubApi.RedirectRequestBehavior(returnUrl, state)`.
- Use `HubApi.CashlinkTheme.GENERIC` for brand-neutral cashlinks or pick seasonal themes when appropriate.

## Atomic Swaps (privileged)

`setupSwap()` and `refundSwap()` are exposed only to privileged origins (the official Nimiq wallet and self-hosted Hub
instances that whitelist your domain). They orchestrate Hash Time-Locked Contracts for NIM, Bitcoin, Polygon, and fiat
legs. If you maintain such an environment, consult `client/PublicRequestTypes.ts` in the Hub repository for the precise
request structures. Public integrations on hub.nimiq.com should rely on external swap services instead.

## Multi-Chain Helpers (privileged)

The Bitcoin and Polygon helpers—`activateBitcoin`, `signBtcTransaction`, `addBtcAddresses`, `activatePolygon`, and
`signPolygonTransaction`—also require a privileged origin. Their payloads depend on detailed chain metadata (UTXO
information for Bitcoin, OpenGSN relay objects for Polygon). Unless you operate a custom Hub deployment, focus on the NIM
methods documented in the other guides.

## Chain Comparison

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Nimiq
    </th>
    
    <th>
      Bitcoin
    </th>
    
    <th>
      Polygon
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Address Format
    </td>
    
    <td>
      <code>
        NQ...
      </code>
    </td>
    
    <td>
      <code>
        bc1...
      </code>
      
      , <code>
        1...
      </code>
      
      , <code>
        3...
      </code>
    </td>
    
    <td>
      <code>
        0x...
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Unit
    </td>
    
    <td>
      Luna (1 NIM = 100k Luna)
    </td>
    
    <td>
      Satoshi (1 BTC = 100M)
    </td>
    
    <td>
      Wei (1 MATIC = 1e18)
    </td>
  </tr>
  
  <tr>
    <td>
      Confirmation Time
    </td>
    
    <td>
      ~1 second
    </td>
    
    <td>
      ~10–60 minutes
    </td>
    
    <td>
      ~2 seconds
    </td>
  </tr>
  
  <tr>
    <td>
      Transaction Fee
    </td>
    
    <td>
      Very low/free
    </td>
    
    <td>
      Variable (sat/vB)
    </td>
    
    <td>
      Variable (Gwei)
    </td>
  </tr>
  
  <tr>
    <td>
      Smart Contracts
    </td>
    
    <td>
      ✅ Yes
    </td>
    
    <td>
      ❌ Limited
    </td>
    
    <td>
      ✅ Yes (EVM)
    </td>
  </tr>
</tbody>
</table>

Understanding these differences helps when you build dashboards or display balances from multiple chains.

## Next Steps

- Review the [API Reference](https://nimiq.dev/hub/api-reference) for a method-by-method overview.
- Follow the [Integration Guide](https://nimiq.dev/hub/guide/integration) for workflow best practices.
- Check out the [Starter Template](https://github.com/onmax/nimiq-starter/tree/main/starters/hub-api-ts) for working examples.


## Sitemap

See the full [sitemap](https://nimiq.dev/sitemap.md) for all pages.