# Tempo Wallet

Tempo Wallet is the first-party wallet for balances, transfers, and deposits.

> [!NOTE]
> The reference layouts on this page are compositions of library components and `style`, not shipped components. `@tempoxyz/ds` exports no `WalletOverview` or `SendReview`. Copy a layout into your app and adapt it.

## Overview

Tempo Wallet runs at [wallet.tempo.xyz](https://wallet.tempo.xyz). You sign in with a passkey, then send, receive, deposit, and swap stablecoins, and manage private balances in Zones.

Roles:

* **Account Holders:** Hold, send, and receive stablecoins such as pathUSD and USDC.e.
* **Developers and Agents (MPP):** Pay for API requests. Access keys permit an app or agent to spend within limits you approve.

## Surfaces

* **Web (@tempoxyz/ds):** wallet.tempo.xyz on desktop browsers.
* **Mobile Web (@tempoxyz/ds):** The same app in iOS and Android browsers.
* **Terminal (CLI):** Tempo Wallet CLI, built outside this library.

No native iOS or Android app is documented. The Apple Pay deposit option is the only flow tied to a device. It needs a US debit card and an iOS device.

## Key Screens

### Overview

```tsx
import { Amount, Button, Grid, Hex, Identicon, ListGroup, style, Surface, TokenLogo, Tooltip } from '@tempoxyz/ds'
import { AddFunds, ArrowDownLeft, Privacy, Send, SwapHorizontal } from '@tempoxyz/ds/icons'

export const fill = true
const account = '0x0b2c69c5c1bbd3f8b642c8d8a3c8a903f780f9b2'

const balances = [
  {
    address: '0x20c0000000000000000000000000000000000000',
    amount: '8420.00',
    name: 'PathUSD',
    symbol: 'pathUSD',
    units: '8,420.00',
  },
  {
    address: '0x20c000000000000000000000b9537d11c60e8b50',
    amount: '3170.32',
    name: 'Bridged USDC (Stargate)',
    symbol: 'USDC.e',
    units: '3,170.32',
  },
]

export function Demo() {
  return (
    <div {...styles.page()}>
      <header {...styles.account()}>
        <Identicon address={account} aria-hidden size="32" />
        <Hex.Root value={account} {...styles.address()}>
          <Hex.Text />
          <Hex.Copy aria-label="Copy wallet address" />
        </Hex.Root>
      </header>

      <Surface>
        <p {...styles.caption()}>Total balance</p>
        <Amount currency="USD" size="xl" value="12840.32" />
        <div {...styles.actions()}>
          <Button>
            <Send />
            Send
          </Button>
          <Button variant="secondary">
            <ArrowDownLeft />
            Receive
          </Button>
          <Button variant="secondary">
            <AddFunds />
            Deposit
          </Button>
          <Button variant="secondary">
            <SwapHorizontal />
            Swap
          </Button>
        </div>
      </Surface>

      <Grid fit="large" gap="16">
        <Surface>
          <Surface.Header>
            <Surface.Title>Balances</Surface.Title>
          </Surface.Header>
          <ListGroup.Root>
            {balances.map((balance) => (
              <ListGroup.Row key={balance.address}>
                <TokenLogo address={balance.address} />
                <ListGroup.Info>
                  <ListGroup.Title>{balance.name}</ListGroup.Title>
                  <ListGroup.Description>
                    {balance.units} {balance.symbol}
                  </ListGroup.Description>
                </ListGroup.Info>
                <Amount currency="USD" value={balance.amount} />
                <Tooltip.Root>
                  <Tooltip.Trigger
                    aria-label={`Send ${balance.name}`}
                    render={<Button shape="icon" size="small" variant="tertiary" />}
                  >
                    <Send />
                  </Tooltip.Trigger>
                  <Tooltip.Popup>Send {balance.name}</Tooltip.Popup>
                </Tooltip.Root>
              </ListGroup.Row>
            ))}
            <ListGroup.Row action="navigation" render={<a href="#zones" />}>
              <span {...styles.zone()}>
                <Privacy />
              </span>
              <ListGroup.Info>
                <ListGroup.Title>Private balance</ListGroup.Title>
                <ListGroup.Description>Held in a zone</ListGroup.Description>
              </ListGroup.Info>
              <Amount currency="USD" value="1250.00" />
            </ListGroup.Row>
          </ListGroup.Root>
        </Surface>

        <Surface>
          <Surface.Header>
            <Surface.Title>Activity</Surface.Title>
            <Button size="small" variant="tertiary">
              View all
            </Button>
          </Surface.Header>
          <ListGroup.Root>
            <ListGroup.Row>
              <ListGroup.Info>
                <ListGroup.Title>Received from 0x3c44…93bc</ListGroup.Title>
                <ListGroup.Description>Today, 9:41 AM</ListGroup.Description>
              </ListGroup.Info>
              <Amount sign="+" symbol="pathUSD" value="250.00" />
            </ListGroup.Row>
            <ListGroup.Row action="navigation" render={<a href="#access-key-activity" />}>
              <ListGroup.Info>
                <ListGroup.Title>Access Key activity</ListGroup.Title>
                <ListGroup.Description>3 transactions</ListGroup.Description>
              </ListGroup.Info>
              <Amount sign="−" symbol="pathUSD" value="0.08" />
            </ListGroup.Row>
            <ListGroup.Row>
              <ListGroup.Info>
                <ListGroup.Title>Sent to 0x91bd…07e1</ListGroup.Title>
                <ListGroup.Description>Yesterday, 4:18 PM</ListGroup.Description>
              </ListGroup.Info>
              <Amount sign="−" symbol="USDC.e" value="48.50" />
            </ListGroup.Row>
          </ListGroup.Root>
        </Surface>
      </Grid>
    </div>
  )
}

namespace styles {
  export const account = style({ alignItems: 'center', columnGap: '12', display: 'flex' })

  export const actions = style({
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8',
    marginBlockStart: '24',
  })

  export const address = style({ minWidth: '0' })

  export const caption = style({
    color: 'content.secondary',
    margin: '0',
    marginBlockEnd: '4',
    typography: 'body.b2',
  })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'flex',
    flexDirection: 'column',
    padding: '16',
    rowGap: '16',
  })

  export const zone = style({
    alignItems: 'center',
    backgroundColor: 'container.strong',
    borderRadius: 'full',
    cornerShape: 'round',
    display: 'inline-flex',
    flexShrink: '0 !custom',
    height: '24',
    justifyContent: 'center',
    width: '24',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Products/WalletOverview.tsx)

The overview leads with the total balance in USD, then the actions that move funds. On wide screens, Balances and Activity sit side by side. In a narrow column, they stack.

* **Wallet Address (Hex.Copy):** An identicon and the copyable address that others send to.
* **Total (size=xl):** Shows the total in USD.
* **Actions (primary):** Send is primary. Receive, Deposit, and Swap are secondary.
* **Balances (ListGroup):** A token icon, name, units, USD value, and a Send button.
* **Private Balance (navigation):** A row that opens Zones.
* **Access Key Activity (navigation):** Opens the list of MPP charges.

Patterns:

* [Payments](/docs/patterns/payments) for the Send, Receive, Deposit, and Swap entry points.
* [Blockchain Values](/docs/patterns/blockchain-values) for the address, token units, and USD values.
* [Tables and Lists](/docs/patterns/tables-and-lists) for balance and activity rows.

### Send Review

```tsx
import { Alert, Amount, Button, Hex, Identicon, ListGroup, style, Surface, TokenLogo } from '@tempoxyz/ds'
import { useEffect, useState } from 'react'

export const fill = true
const recipient = '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc'

export function Demo() {
  const [state, setState] = useState<'review' | 'sending' | 'sent'>('review')

  useEffect(() => {
    if (state !== 'sending') return
    const timer = setTimeout(() => setState('sent'), 1200)
    return () => clearTimeout(timer)
  }, [state])

  return (
    <div {...styles.page()}>
      <Surface {...styles.panel()}>
        <Surface.Header>
          <Surface.Title>{state === 'sent' ? 'Sent' : 'Review send'}</Surface.Title>
        </Surface.Header>

        <div {...styles.hero()}>
          <Amount align="center" size="lg" symbol="pathUSD" value="250.00" />
        </div>

        <ListGroup.Root>
          <ListGroup.Row>
            <ListGroup.Label>To</ListGroup.Label>
            <span {...styles.recipient()}>
              <Identicon address={recipient} aria-hidden size="24" />
              <Hex.Root value={recipient} {...styles.hex()}>
                <Hex.Text />
                <Hex.Copy aria-label="Copy recipient address" />
              </Hex.Root>
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Token</ListGroup.Label>
            <TokenLogo address="0x20c0000000000000000000000000000000000000" size="small" />
            PathUSD
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Network</ListGroup.Label>
            Tempo
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Note</ListGroup.Label>
            Invoice 1042
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Network fee</ListGroup.Label>
            <Amount currency="USD" precise value="0.001" />
          </ListGroup.Row>
        </ListGroup.Root>

        {state === 'sent' ? (
          <>
            <Alert intent="positive" {...styles.notice()}>
              <Alert.Icon />
              <Alert.Content>Sent 250.00 pathUSD to 0x3c44…93bc.</Alert.Content>
            </Alert>
            <div {...styles.actions()}>
              <Button.Link href="https://explore.tempo.xyz/" variant="secondary">
                View in explorer
              </Button.Link>
              <Button onClick={() => setState('review')}>Done</Button>
            </div>
          </>
        ) : (
          <>
            <p {...styles.warning()}>
              Check the address before you confirm. Funds sent to the wrong address may not be
              recoverable.
            </p>
            <div {...styles.actions()}>
              <Button disabled={state === 'sending'} variant="secondary">
                Back
              </Button>
              <Button loading={state === 'sending'} onClick={() => setState('sending')}>
                Confirm send
              </Button>
            </div>
          </>
        )}
      </Surface>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginBlockStart: '24',
    '@media (max-width: 40rem)': {
      flexDirection: 'column-reverse',
      rowGap: '8',
    },
  })

  export const hero = style({ paddingBlock: '24' })

  export const hex = style({ minWidth: '0' })

  export const notice = style({ marginBlockStart: '24' })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'flex',
    justifyContent: 'center',
    padding: '16',
  })

  export const panel = style({ maxWidth: '28rem !custom', width: '100% !custom' })

  export const recipient = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    minWidth: '0',
  })

  export const warning = style({
    color: 'content.secondary',
    margin: '0',
    marginBlockStart: '24',
    typography: 'body.b3',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Products/WalletSendReview.tsx)

Send collects a recipient address, amount, token, and optional note. The review shows them with the network fee before you confirm.

* **Transfer Amount (symbol):** Shows the value of the transfer in large type and in token units.
* **Details (ListGroup.Label):** Lists the recipient, token, network, note, and network fee.
* **Recipient (Hex):** An identicon beside the address. Both ends stay visible for comparison.
* **Confirm (loading):** The only primary action. It is busy during the submit. A success alert with an Explorer link replaces it.

Patterns:

* [Payments](/docs/patterns/payments) for the review and confirmation step.
* [Blockchain Values](/docs/patterns/blockchain-values) for the truncated address and the fee.
* [Destructive Actions](/docs/patterns/destructive-actions) for what can't be undone.

## Content

### Show USD for Holdings and Token Units for Transfers

* **Holdings:** Show balances in USD.
* **Transfers:** Show the token amount, since the transaction carries it. The review states 250.00 pathUSD, not $250.00.

### Label Every Address by What It Receives

* **Wallet address:** Receives from other Tempo Wallets.
* **Deposit address:** Shown in the Deposit crypto flow, for one chain and token.

**Do:** Label each address by purpose, such as Wallet address or Deposit address, and name the chain and
token beside a deposit address.

**Don't:** Show a bare 0x address without a label, or ask for the wallet address inside a deposit
flow.

### Say Where a Deposit Option Works

Deposit offers Buy MACH, Fiat/cards, Deposit crypto, and Claim referral code. Availability depends on the country and the enabled onramps.

State a limit beside the option, such as US only for Apple Pay, not after the choice.

### Group Machine Payments

An MPP session can produce several charges. Show the session as one row, such as Access Key activity with 3 transactions. List each charge when the row expands.

### Don't Promise Recovery

Tempo can't recover a deleted passkey, and a transfer to the wrong address may be lost. State both in sign-in and review copy. Tell people to save their passkey in a password manager that syncs across devices.

## Open Gaps

The library has no part for these needs yet. Before you add one, propose it as an issue in the Design System project.

* **Address Field:** Nothing checks a 0x address or suggests recipients. Use an input and an error, or an autocomplete.
* **QR Scanning:** Renders a QR code but can't read one from the camera.
* **Mobile Blockchain Parts:** `@tempoxyz/ds/mobile` has no amount, address, identicon, rows, token, or QR counterpart.
* **Activity Grouping:** Each screen composes grouped MPP rows again. No part names the session or its charge count.

## Related

[Payments](/docs/patterns/payments)

Covers send, receive, and deposit flows.

[Blockchain Values](/docs/patterns/blockchain-values)

Covers addresses, amounts, and fees.

[Amount](/docs/components/amount)

Use for USD and token values.

[Hex](/docs/components/hex)

Use for addresses and hashes.

[ListGroup](/docs/components/list-group)

Use for balances and activity.

[TokenLogo](/docs/components/token-logo)

Use for token icons.
