> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# KeyStone Elements

> Plug-and-play settlement integration for platforms. Embed in minutes, customize everything.

KeyStone Elements is a set of packages that let platforms integrate settlement functionality into their applications with minimal code. Think Stripe Elements, but for settlement orchestration.

## Packages

| Package                     | What it does                        | When to use                                              |
| --------------------------- | ----------------------------------- | -------------------------------------------------------- |
| `@keystoneos/react`         | React hooks and provider (headless) | You want full UI control with your own components        |
| `@keystoneos/react-ui`      | Pre-built styled components         | You want drop-in widgets that just work                  |
| `@keystoneos/elements-core` | Framework-agnostic core             | You're not using React, or building a custom integration |
| `@keystoneos/node`          | Server-side helpers                 | Creating session tokens, handling webhooks               |

## Integration Tiers

Elements supports three integration patterns depending on how your platform handles custody and signing:

### Tier 1: View-Only

Your backend handles everything via the SDK and webhooks. The frontend only displays settlement status.

```tsx theme={null}
import { KeystoneProvider, useSettlement } from '@keystoneos/react';

function SettlementTracker({ id }) {
  const { settlement, isLoading } = useSettlement(id);
  if (isLoading) return <Spinner />;
  return <div>State: {settlement.state}</div>;
}
```

### Tier 2: Interactive + Custody (Most Common)

The widget collects user decisions (confirm, deposit). Deposit execution routes through your backend to a custody provider like Fireblocks or BitGo.

```tsx theme={null}
<KeystoneProvider
  sessionToken={token}
  actionDelegates={{
    onDepositRequired: async (leg, info) => {
      // Your backend submits to Fireblocks
      const result = await fetch('/api/deposit', {
        method: 'POST',
        body: JSON.stringify(info),
      }).then(r => r.json());
      return { txHash: result.txHash };
    },
  }}
>
  <YourSettlementUI />
</KeystoneProvider>
```

### Tier 3: Full Self-Service

End-users connect their own wallets. The widget handles on-chain transactions directly via wagmi.

```tsx theme={null}
<WagmiProvider config={wagmiConfig}>
  <KeystoneProvider sessionToken={token}>
    <YourSettlementUI />
  </KeystoneProvider>
</WagmiProvider>
```

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant PB as Platform Backend
    participant PF as Platform Frontend
    participant KS as KeyStone API

    PB->>KS: POST /v1/sessions (M2M auth)
    KS-->>PB: Session token (scoped JWT)
    PB-->>PF: Pass session token
    PF->>KS: API calls with session token
    KS-->>PF: Settlement data, real-time updates
    PF->>PB: onDepositRequired (Tier 2)
    PB->>KS: POST deposit-calldata
    PB->>PB: Submit to Fireblocks
```

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/elements/getting-started">
    Install and set up your first integration in 5 minutes.
  </Card>

  <Card title="Hooks Reference" icon="code" href="/hooks/use-settlement">
    Full API reference for all React hooks.
  </Card>
</CardGroup>