@sky-mavis/nana-app-sdk

SDK for building mini apps that run inside the NanaPay wallet. Works in two modes automatically:

• Injected -- app runs inside the wallet's WebView with window.ethereum injected
• Universal Link -- app runs in an external browser, redirects into the wallet via https://nanapay.co/open

The SDK detects the mode on first call. You never need to check or switch manually.

Installation

npm install @sky-mavis/nana-app-sdk

Quick Start

import { connect, signMessage, sendTransaction, disconnect } from '@sky-mavis/nana-app-sdk'

// 1. Connect and request permissions in one step
const { address, chainId, permissions } = await connect({
  requiredPermissions: ['address'],
  defaultPermissions: ['address', 'signMessage', 'sendTransaction'],
})

// 2. Sign a message (requires signMessage permission)
const signature = await signMessage('Hello from my mini app!')

// 3. Send a transaction (requires sendTransaction permission)
const txHash = await sendTransaction({
  to: '0x1234...abcd',
  value: '1000000000000000000', // 1 RON in wei
})

// 4. Disconnect when done
await disconnect()

API Reference

connect(options?)

Connect to the wallet. Accepts optional permission configuration.

const { address, chainId, permissions } = await connect({
  requiredPermissions: ['address'],
  defaultPermissions: ['address', 'email', 'signMessage', 'sendTransaction'],
})

ConnectOptions

| Field | Type | Default | Description | |-------|------|---------|-------------| | requiredPermissions | Permission[] | ['address'] | Permissions the user must grant | | defaultPermissions | Permission[] | All permissions | Pre-selected permissions shown to the user |

Returns Promise<ConnectResult> with { address: string, chainId: number, permissions: Record<Permission, boolean> }.

requestPermissions(permissions)

Request specific permissions from the user. A permission approval sheet is shown to the user.

const granted = await requestPermissions(['address', 'email', 'signMessage'])
// { address: true, email: true, signMessage: false }

Available permissions: address, email, name, signMessage, sendTransaction.

getUserInfo(fields)

Get user information for the requested fields. Requires corresponding permissions (email, name, address).

const info = await getUserInfo(['email', 'name', 'address'])
// { email: '[email protected]', name: 'Alice', address: '0x...' }

signMessage(message)

Request the user to sign a message. Requires signMessage permission. Shows a confirmation sheet.

const signature = await signMessage('Please sign this message')

sendTransaction(tx)

Request the user to send a transaction. Requires sendTransaction permission. Shows a confirmation sheet.

const txHash = await sendTransaction({
  to: '0x1234...abcd',
  value: '1000000000000000000',
  data: '0x',       // optional
  gasLimit: '21000', // optional
})

getProvider()

Get the low-level EIP-1193 compatible provider for advanced use cases.

const provider = await getProvider()
const blockNumber = await provider.request({ method: 'eth_blockNumber' })

disconnect()

Disconnect and reset the SDK. Resets the internal singleton so the next call re-detects the mode.

await disconnect()

detectMode()

Check which mode the SDK will use without initializing. Useful for conditional UI. Returns a Promise because it performs EIP-6963 provider discovery.

import { detectMode } from '@sky-mavis/nana-app-sdk'

const mode = await detectMode()
if (mode === 'injected') {
  // Running inside the wallet WebView
} else {
  // Running in an external browser
}

configure(config)

Optional. Override defaults before first use. Must be called before any other SDK function.

import { configure } from '@sky-mavis/nana-app-sdk'

configure({
  walletUrl: 'https://custom-wallet.example.com',
})

Only relevant for universal-link mode. If not called, defaults to https://nanapay.co.

Supported RPC Methods

These are the wallet RPC methods available through getProvider().request():

| Method | Permission | User Approval | |--------|-----------|---------------| | wallet_connect | None | Yes | | eth_chainId | None | No | | eth_accounts | address | No | | personal_sign | signMessage | Yes | | eth_sendTransaction | sendTransaction | Yes | | wallet_getUserInfo | email/name | No | | wallet_requestPermissions | None | Yes | | wallet_getPermissions | None | No | | wallet_revokePermissions | None | No |

Permissions

| Permission | Description | |-----------|-------------| | address | View the user's wallet address | | email | View the user's email address | | name | View the user's display name | | signMessage | Request message signatures | | sendTransaction | Request transaction approvals |

Advanced: EIP-6963 Provider Discovery

For custom integrations, you can access the underlying EIP-6963 discovery functions:

import { getNanapayProvider, requestProviders, NANAPAY_RDNS } from '@sky-mavis/nana-app-sdk'

// Get the NanaPay provider directly
const provider = await getNanapayProvider()

// Or discover all EIP-6963 providers
const providers = await requestProviders()

Constants exported: NANAPAY_RDNS, EIP6963_DISCOVERY_DELAY, ALL_PERMISSIONS, DEFAULT_WALLET_URL

Build

npm run build       # TypeScript check + Vite library build
npm run typecheck   # TypeScript check only
npm run dev         # Watch mode
npm run lint        # ESLint check
npm run lint:fix    # ESLint with auto-fix

Output: dist/index.mjs (ESM), dist/index.cjs (CJS), dist/index.d.ts (types).

License

MIT