# Movement Mini Apps SDK

> Build blockchain mini apps that run natively inside Movement wallet.
> Web apps (HTML/CSS/JS) with automatic wallet connection, transaction signing, and native device APIs.

## What Are Mini Apps?

Mini apps are lightweight web applications that run inside the Movement "Move Everything" super app. Users don't need to install anything - your app loads instantly inside their wallet with full blockchain capabilities.

**Key benefits:**
- Wallet is already connected (no "Connect Wallet" flow needed)
- Native device access: camera, haptics, notifications, biometrics
- Instant distribution to all Movement wallet users
- Build with any web framework: React, Next.js, vanilla JS

## Installation

```bash
npm install @movement-labs/miniapp-sdk
```

## Quick Start (React)

```typescript
import { useMovementSDK } from '@movement-labs/miniapp-sdk';

function App() {
  const { sdk, address, isConnected, isLoading } = useMovementSDK();

  if (isLoading) return <div>Loading...</div>;

  async function sendMove() {
    const result = await sdk.sendTransaction({
      function: '0x1::aptos_account::transfer',
      arguments: [recipientAddress, '100000000'], // 1 MOVE (8 decimals)
      type_arguments: []
    });
    console.log('TX Hash:', result.hash);
  }

  return <button onClick={sendMove}>Send 1 MOVE</button>;
}
```

## Quick Start (Vanilla JS)

```javascript
// SDK is available on window.movementSDK
const sdk = window.movementSDK;

// Wait for SDK to be ready
await sdk.ready();

// Send transaction
const result = await sdk.sendTransaction({
  function: '0x1::aptos_account::transfer',
  arguments: [recipientAddress, '100000000'],
  type_arguments: []
});
```

## Core APIs

### Blockchain
- `sdk.sendTransaction({ function, arguments, type_arguments })` - Execute transactions
- `sdk.view({ function, function_arguments, type_arguments })` - Read on-chain data (no signing)
- `sdk.waitForTransaction(hash)` - Wait for confirmation
- `sdk.address` - Connected wallet address
- `sdk.getBalance()` - Get MOVE balance

### MNS (Movement Name Service)
- `sdk.mns.getTargetAddress(name)` - Resolve .move name to wallet address
- `sdk.mns.getPrimaryName(address)` - Get primary .move name for a wallet address (reverse lookup)

### Device Features
- `sdk.scanQRCode()` - Open camera to scan QR
- `sdk.haptic({ type, style })` - Tactile feedback (impact/notification/selection)
- `sdk.notify({ title, body })` - Push notifications
- `sdk.share({ title, message, url })` - Native share sheet
- `sdk.Clipboard.writeText(text)` - Copy to clipboard

### UI Components
- `sdk.MainButton.setText(text)` / `.show()` / `.onClick(fn)` - Fixed bottom button
- `sdk.showAlert(message)` - Simple alert
- `sdk.showConfirm(message)` - OK/Cancel dialog
- `sdk.showPopup({ title, message, buttons })` - Custom popup

### Storage
- `sdk.CloudStorage.setItem(key, value)` - Persist data
- `sdk.CloudStorage.getItem(key)` - Retrieve data

## Important Patterns

### Always check SDK is ready
```typescript
// React: useMovementSDK handles this automatically
const { sdk, isLoading } = useMovementSDK();
if (isLoading) return <Loading />;

// Vanilla JS: call ready() first
await window.movementSDK.ready();
```

### Amounts are strings (8 decimals for MOVE)
```typescript
// 1 MOVE = 100000000 (8 decimals)
arguments: ['100000000'] // ✅ String
arguments: [100000000]   // ❌ May lose precision
```

### Handle user rejection
```typescript
try {
  await sdk.sendTransaction({...});
} catch (error) {
  if (error.code === 'USER_REJECTED') {
    // User cancelled - don't show error
  }
}
```

### Transaction function format
```typescript
function: 'address::module::function'
// Example: '0x1::aptos_account::transfer'
```

### MNS name resolution
```typescript
// Resolve .move name to address (returns AccountAddress object)
const result = await sdk.mns.getTargetAddress('alice.move');

// Convert AccountAddress to hex string
if (result && typeof result === 'object' && 'data' in result) {
  const bytes = Object.values(result.data);
  const address = '0x' + bytes.map(b => b.toString(16).padStart(2, '0')).join('');
}

// Reverse lookup: get name for address
const name = await sdk.mns.getPrimaryName('0x742d35Cc...');
// Returns: 'alice' or null
```

## Rate Limits
- Transactions: 300/day per user
- Notifications: 50/day per user
- Other commands: 1000/hour

## Common Error Codes
- `USER_REJECTED` - User cancelled
- `INSUFFICIENT_BALANCE` - Not enough funds
- `RATE_LIMIT_EXCEEDED` - Too many requests
- `NETWORK_ERROR` - Connection issues

## React Hooks
- `useMovementSDK()` - Main hook: sdk, address, isConnected, sendTransaction
- `useMovementAccount()` - Account info
- `useMovementTheme()` - Light/dark mode
- `useAnalytics()` - Event tracking

---

## Full Documentation

### Introduction

- [Quick Start](/quick-start.md)

### Quick Start

- [Installing](/quick-start/installing.md)
- [Commands](/quick-start/commands.md)
- [Responses](/quick-start/responses.md)
- [Testing](/quick-start/testing.md)

### Commands

- [Commands](/commands.md)
- [View Function](/commands/view.md)
- [Send Transaction](/commands/send-transaction.md)
- [Scan QR Code](/commands/scan-qr.md)
- [Haptic Feedback](/commands/haptic.md)
- [Notifications](/commands/notifications.md)

### Examples

- [Next.js / React](/examples/nextjs.md)
- [Vanilla JavaScript](/examples/vanilla.md)
- [Starter App](/examples/starter.md)
- [Scaffold App](/examples/scaffold.md)
- [Social App](/examples/social.md)

### Guidelines

- [Design Guidelines](/guidelines/design.md)

### Technical Reference

- [SDK API Reference](/reference/sdk-api.md)

### Publishing

- [Publishing Your Mini App](/publishing.md)
- [App Publisher](/publishing/publisher.md)

### Other

- [Advanced Transactions](/guides/advanced-transactions.md)
- [AI Mini App Builder](/ai-builder.md)
- [Publishing Your Mini App](/guides/publishing.md)
- [SDK Overview](/sdk/overview.md)
- [Security Best Practices](/guides/security.md)
- [Unity WebGL](/examples/unity.md)


---

For llms-full.txt with complete API reference and examples, fetch: /llms-full.txt