Skip to content

Developer docs

Build with NanChat

Integrate NanChat into your web app with universal links. No server-side dependency on NanChat. Everything works through public Nano cryptography.

Send Request

Use a universal link to open NanChat with the recipient address and amount already filled in. The user only needs to confirm the transaction. This works on iOS and Android.

URL format

https://nanchat.com/?uri=<PREFIX>:<ADDRESS>?amount=<RAW_AMOUNT>
  • PREFIX: one of nano, ban, usd (NanUSD), or any other supported network prefix. This tells NanChat which network to use for the transaction.
  • ADDRESS: the recipient address for that network (e.g. nano_..., ban_..., usd_...).
  • RAW_AMOUNT: the amount in the smallest unit (raw) for that network. Optional.

Example: send NanUSD

https://nanchat.com/?uri=usd:usd_3i5ychrw4ajk5tj5y9ocwr5t9j3tej7t1bwrkcm6p3p1wsu5ny5q371d3bxh?amount=1000

Example: send Nano

https://nanchat.com/?uri=nano:nano_1banexkcfuieufzxksfrxqf6xy8e57ry1zdtq9yn7jntzhpwu4pg4hajojmq?amount=1000000000000000000000000000

HTML button

<a href="https://nanchat.com/?uri=nano:nano_3xxx...xxx?amount=1000000000000000000000000000000" style="text-decoration: none;">
  <button style="display: inline-flex; align-items: center; gap: 8px; background: #000000; color: #fff; border: none; padding: 10px 18px; border-radius: 6px; font-size: 15px; font-weight: 600; cursor: pointer;">
    <img src="https://bucket.nanwallet.com/logo/nanchat-pay-icon-01.svg"
         alt="" width="20" height="20">
    Pay with NanChat
  </button>
</a>

Preview:

On mobile, the link opens the NanChat app if installed; otherwise it falls back to the web page where the user can download the app and complete the request.

Login with NanChat

“Login with NanChat” lets a user prove ownership of a Nano address by signing a server-generated nonce. The signature is verified on your backend with the user’s public key. No password, no third-party identity provider.

Flow

  1. Your server generates a random nonce and stores it in the user’s pending session.
  2. You render a Login with NanChat button pointing to a nanauth://sign universal link wrapped by https://nanchat.com/?uri=.
  3. The user opens the link. NanChat prompts them to sign the message.
  4. On success, NanChat calls your url callback with the signature, account, and message.
  5. Your /callback endpoint verifies the signature withnanocurrency-web, checks that the message contains your hostname and the expected nonce, and issues a session cookie.

1. Build the login link

const nonce = crypto.randomBytes(16).toString('hex'); // store on the server

const message  = `Login to xxxxx.com nonce: ${nonce}`;
const callback = 'https://xxxxx.com/callback';

const nanauth = `nanauth://sign?message=${encodeURIComponent(message)}` +
                `&url=${encodeURIComponent(callback)}`;

const loginUrl = `https://nanchat.com/?uri=${nanauth}`;
For login requests, make sure that the message contains “Login to <your hostname>”. This enforces that the submit url matches your hostname, to prevent phishing attacks. Adding “Login to” also shows a Login modal instead of a signature request modal.

Render it as a button:

<a href="https://nanchat.com/?uri=nanauth://sign?message=Login%20to%20example.com%20nonce%3A%20NONCE&url=https%3A%2F%2Fnanchat.com%2Ftest%2Fcallback" style="text-decoration: none;">
  <button style="display: inline-flex; align-items: center; gap: 8px; background: #000000; color: #fff; border: none; padding: 10px 18px; border-radius: 6px; font-size: 15px; font-weight: 600; cursor: pointer;">
    <img src="https://nanchat.com/images/nanchat.svg"
         alt="" width="20" height="20">
    Login with NanChat
  </button>
</a>

Preview:

2. Verify the callback on your server

NanChat POSTs the signature payload to your url as JSON, withaccount, signature, and message. Derive the public key from the account with tools.addressToPublicKey, then verify the signature withtools.verify fromnanocurrency-web:

import { tools } from 'nanocurrency-web';

app.post('/callback', express.json(), (req, res) => {
  const { account, signature, message } = req.body;

  // 1. The message must be "Login to <our hostname> nonce: ..." — this is what
  //    stops a phishing site from replaying a signature collected for another domain.
  if (!message || !message.startsWith(`Login to ${req.hostname} nonce: `)) {
    return res.status(400).json({ error: 'Message does not match this domain' });
  }

  // 2. The message must contain the nonce we issued for this session.
  const expectedNonce = req.session.pendingNonce;
  if (!message.includes(`nonce: ${expectedNonce}`)) {
    return res.status(400).json({ error: 'Invalid or expired nonce' });
  }

  // 3. Derive the public key from the claimed account.
  const publicKey = tools.addressToPublicKey(account);

  // 4. Verify the signature. NanChat signs the message prefixed with
  //    "Signed Message: "
  const valid = tools.verify(publicKey, signature, message);
  if (!valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 5. Consume the nonce and issue a session cookie.
  req.session.pendingNonce = null;
  req.session.user = { account };
  res.json({ ok: true });
});
  • Nonces must be single-use, random (≥ 128 bits) and short-lived (e.g. 5 minutes). They prevent replay attacks.
  • The message hostname (Login to example.com) and the url callback hostname must match. Verify both on your server, don’t rely on NanChat alone.

Track opens from a chat group

When a user opens your app from a group chat, NanChat appends nanchat-chat-id=<chat_id> to your app url. You can use this to send updates to the corresponding chat group.

You can also check the User-Agent header to see if the user opened your app from NanChat. The User-Agent contains NanChat.

Questions or feedback?

Reach out at [email protected] or viaNanChat Team on NanChat.