# @stableyard/widget

Version 1 deposit-first stablecoin widget powered directly by the Stableyard routing API.

The widget lets an integrator define the recipient, settlement chain, settlement
token, and optional fixed amount. Users can then pay from supported EVM, Solana,
and Movement wallets, or use a deposit address / QR flow.

## Install

```bash
npm install @stableyard/widget@1
```

Peer dependencies:

```bash
npm install react react-dom @privy-io/react-auth
```

## React: Inline

```tsx
import { StableyardWidget } from '@stableyard/widget'

export function DepositInline() {
  return (
    <StableyardWidget
      recipient="0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
      destination={{
        chainId: 8453,
        token: 'USDC',
        tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        decimals: 6,
        amount: '25',
      }}
      mode="inline"
      onSuccess={(result) => console.log('Settled', result.sessionId)}
    />
  )
}
```

## React: Button / Modal

```tsx
import { StableyardWidget } from '@stableyard/widget'

export function DepositButton() {
  return (
    <StableyardWidget
      recipient="0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
      destination={{
        chainId: 8453,
        token: 'USDC',
        tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        decimals: 6,
        amount: '25',
      }}
      mode="modal"
      buttonText="Deposit"
      showCloseButton
      onSuccess={(result) => console.log('Settled', result.sessionId)}
    />
  )
}
```

## Standalone Script

For plain HTML sites, CMS pages, and POS webviews:

```html
<button id="deposit">Deposit</button>
<script src="https://unpkg.com/@stableyard/widget@1/standalone.js"></script>
<script>
  Stableyard.init({
    theme: 'light',
    accentColor: '#ff820a'
  })

  document.getElementById('deposit').onclick = function () {
    Stableyard.pay({
      recipient: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582',
      destination: {
        chainId: 8453,
        token: 'USDC',
        tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        decimals: 6,
        amount: '25'
      },
      private: true,
      onSuccess: function (result) {
        console.log('Settled', result.sessionId)
      }
    })
  }
</script>
```

`Stableyard.pay()` opens the widget immediately in an overlay. Inline mounting is
also available:

```html
<div id="stableyard-deposit"></div>
<script src="https://unpkg.com/@stableyard/widget@1/standalone.js"></script>
<script>
  Stableyard.mount('#stableyard-deposit', {
    recipient: '0xdFD4ab80E163D6864E26F37540563cBf2E52A582',
    destination: {
      chainId: 8453,
      token: 'USDC',
      tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
      decimals: 6
    }
  })
</script>
```

## Theming

```tsx
<StableyardWidget
  recipient="0xdFD4ab80E163D6864E26F37540563cBf2E52A582"
  destination={{ chainId: 8453, token: 'USDC', amount: '25' }}
  theme="light"
  appearance={{
    variables: {
      colorPrimary: '#ff820a',
      colorBackground: '#ffffff',
      colorText: '#111111',
      colorTextSecondary: '#666666',
      colorBorder: '#e5e5e5',
      colorSuccess: '#00a33c',
      colorError: '#f24900',
      fontFamily: 'Inter, system-ui, sans-serif',
      borderRadius: '16px',
    },
  }}
/>
```

## Supported Flows

- Loads supported chains, tokens, and routes from the routing API.
- Uses `/v1/portfolio` to show eligible connected-wallet balances.
- Creates quotes through `/v1/quote` and orders through `/v1/order`.
- Supports EVM wallet transaction payloads returned by the routing API.
- Supports Solana wallet transfers for Solana deposit-address routes.
- Supports Movement wallet `movePayload` signing through Movement-compatible wallets.
- Shows exact send amount, token, chain, route fees, and status.
- Treats routing `in_progress` as user-confirmed success while settlement continues.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `recipient` | `string` | Destination wallet address. Alias: `to`. |
| `destination.chainId` | `number` | Settlement chain ID. |
| `destination.token` | `string` | Settlement token symbol. |
| `destination.tokenAddress` | `string` | Settlement token address, mint, or Move token address. |
| `destination.decimals` | `number` | Settlement token decimals. |
| `destination.amount` | `string \| number` | Fixed output amount. Omit for open amount. |
| `source` | `object` | Optional preselected source chain/token config. |
| `private` | `boolean` | Requests a private routing order when supported. |
| `executionMode` | `'standard' \| 'atomic' \| 'deposit_address' \| 'boosted'` | Preferred routing action shape. |
| `routeMode` | `'exact_input' \| 'exact_output'` | Quote mode. Fixed amounts default to exact output. |
| `slippageBps` | `number` | Slippage in basis points. |
| `mode` | `'inline' \| 'modal'` | Render directly or behind a button. |
| `buttonText` | `string` | Button label for modal mode. |
| `showCloseButton` | `boolean` | Overrides close-button visibility. Defaults to true in modal mode. |
| `theme` | `'light' \| 'dark' \| 'auto'` | Widget theme. |
| `appearance.variables` | `object` | Theme overrides. |
| `routingApiUrl` | `string` | Override routing API base URL. |
| `privyAppId` | `string` | Optional Privy app id override. |
| `onReady` | `() => void` | Called when a session is ready. |
| `onSuccess` | `(result) => void` | Called once payment is confirmed / settled. |
| `onError` | `(error) => void` | Called on widget errors. |
| `onClose` | `() => void` | Called when dismissed after completion. |
| `onCancel` | `() => void` | Called when an unfinished payment is dismissed. |
| `onStatusChange` | `(status) => void` | Called when session status changes. |

## Scope

This package is intentionally deposit-only. It does not create hosted checkout
sessions, require a merchant account wrapper, or call the old Stableyard backend
payment APIs. Quotes, orders, portfolio checks, and status polling are handled
through the Stableyard routing API deposit flow.
