# Wallets & signing (/docs/swivy/wallets-and-signing)

<Callout type="warn" title="Preview: Swivy is not generally available">
Swivy is a **staging/testnet preview using software custody**, not a production custody service. All six public SDK packages are available at **1.0.1**. Use test assets only. [Set up the preview](/docs/swivy/preview-setup) or [request project access](/docs/swivy/request-access).
</Callout>

**In plain words:** a wallet is an address plus a private key. With Swivy the key stays in the signer (or, in split custody, partly in the user's browser). Your app asks for a signature by submitting an **intent**, the user approves it with a passkey when policy says so, and you get back the result.

## Create or load wallets [#create-or-load-wallets]

Wallets are usually created at login, as your [policy](/docs/swivy/policies) allows. To make sure one exists:

```ts
const evm = await swivy.ensureEmbeddedWallet('evm', { label: 'Primary wallet' });
const sol = await swivy.ensureEmbeddedWallet('solana', { label: 'Primary wallet' });
const wallets = await swivy.listEmbeddedWallets(); // every managed account for this user
```

In React, `useEmbeddedWallets('evm')` gives you `wallets` and `ensureManagedAccount('evm')`.

## Approve first, then sign [#approve-first-then-sign]

If policy requires step-up, get a `challengeId` from a passkey approval and attach it to the intent:

```ts
const approval = await swivy.approveWithPasskey(passkeyAuthMethodId, 'intent_approval');
const challengeId = approval.challenge.challengeId;
```

## Sign a message [#sign-a-message]

```ts
const intent = await swivy.signMessageAndWait({
  accountId: evm.account.id,
  chain: 'evm',
  challengeId,
  payload: { message: 'Sign in to Acme' },
});
console.log(intent.result); // includes the signature
```

Use `messageHex` or `messageBase64` in `payload` for binary messages. On Solana pass `chain: 'solana'`.

## Sign EIP-712 typed data (EVM) [#sign-eip-712-typed-data-evm]

```ts
const intent = await swivy.signTypedDataAndWait({
  accountId: evm.account.id,
  challengeId,
  typedData: {
    domain: { name: 'Acme', version: '1', chainId: 8453 },
    types: { Order: [{ name: 'amount', type: 'uint256' }] },
    primaryType: 'Order',
    message: { amount: '1000000' },
  },
});
```


## Sign a transaction without sending it [#sign-a-transaction-without-sending-it]

```ts
const intent = await swivy.signTransactionAndWait({
  accountId: evm.account.id,
  chain: 'evm',
  challengeId,
  payload: { transaction: { to: '0x1111111111111111111111111111111111111111', value: '0x0', data: '0x' } },
});
```

For Solana, pass `serializedTransactionBase64` instead of `transaction`.

## Send a transaction (execute) [#send-a-transaction-execute]

Swivy signs, optionally [sponsors gas](/docs/swivy/gas-sponsorship), broadcasts through your configured RPC and reports back:

```ts
const intent = await swivy.createTransactionIntentAndWait({
  accountId: evm.account.id,
  chain: 'evm',
  challengeId,
  payload: {
    network: 'base-sepolia',
    transaction: { to: '0x1111111111111111111111111111111111111111', value: '0x0', data: '0x' },
  },
});
console.log(intent.status, intent.result);
```

`payload.network` must be a network your environment has an RPC for: `base-sepolia`, `ethereum-mainnet`, `arbitrum-mainnet`, `optimism-mainnet`, `polygon-mainnet`, `solana-devnet`, `base-sepolia` or `solana-devnet`.

## Intent lifecycle [#intent-lifecycle]

Every call above creates an intent. The `...AndWait` helpers poll until it finishes; you can also create one with `createSigningIntent` or `createTransactionIntent`, then call `getIntent(id)` or `waitForIntent(id)`, or listen for the [webhook](/docs/swivy/webhooks).

| Status | Meaning |
|---|---|
| `pending_step_up` | Needs a passkey approval first. |
| `queued` → `processing` | Accepted, then being signed and sent. |
| `completed` | `result` holds the signature or transaction hash. |
| `failed` | Rejected by policy or failed on chain. |

## Split-custody wallets: sign in the browser [#split-custody-wallets-sign-in-the-browser]

For `split_custody` wallets Swivy can't sign alone. Sign locally after a passkey unlock:

```ts
const signed = await swivy.signMessageLocallyWithPasskey(
  { accountId: wallet.id, chain: 'evm', payload: { message: 'approve local signing' } },
  passkeyAuthMethodId,
);
console.log(signed.result.signature);
```

`signTypedDataLocallyWithPasskey` and `signTransactionLocallyWithPasskey` work the same way. See the [React quickstart](/docs/swivy/react-quickstart) for the full self-custody flow.

## Export and raw signing [#export-and-raw-signing]

`exportManagedAccount` and `rawSign` are escape hatches for hybrid setups. Both are **off unless your policy enables them** and need a step-up challenge (`account_export` for export). Prefer intents.

**Sealed export (preview; requires a compatible signer):**
- The key is encrypted inside Swivy's signer with HPKE (RFC 9180, X25519 + AES-256-GCM) to a one-time key your app generates, so it never travels in clear.
- `exportManagedAccount` does this for you and still returns the key.
- To do it by hand, use `generateExportRecipientKeyPair` and `openSealedExport`.
- Clear-text export requires an explicit policy opt-in. The SDK refuses an unsealed response or mismatched binding; an older signer can return `signer_does_not_support_sealed_export`.
