# Concepts (/docs/swivy/concepts)

<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>

## Accounts: users, logins and wallets [#accounts-users-logins-and-wallets]

Swivy keeps **who someone is** separate from **which wallets they have**, so one user can have several login methods and one wallet per chain without your app inventing its own user model.

| Object | What it is |
|---|---|
| **Identity** | One user inside a project. Its id is the stable user id; you can also store your own `externalUserId` on it. |
| **Auth method** | A way to log in or step up: email, external wallet, passkey, TOTP or SMS. |
| **Managed account** | An embedded wallet Swivy created for the user: chain, address, custody mode and purpose. |
| **Linked wallet** | A wallet the user already had (MetaMask, Phantom and so on) connected to their identity. |
| **Session grant** | Delegated, limited access to one managed account for an agent or backend job. |

Managed accounts also carry a **purpose**: `personal`, `agent`, `recovery` or `treasury`. The same user can have a `personal` wallet they sign with in the browser and an `agent` wallet for automation on the same chain.

## Custody: who holds the key [#custody-who-holds-the-key]

A wallet is a private key. Swivy offers two ways to hold it.

| Mode | How it works | Good for |
|---|---|---|
| `managed_tee` (default) | The key lives in Swivy's isolated signer, a separate service that does nothing but sign. Your app asks for a signature; the key never leaves the signer. Export and raw signing are off unless your policy allows them. | Most apps. Works the same on web, iOS and Android. |
| `split_custody` | The key is split. The user's browser keeps one share; Swivy stores only an encrypted copy of the other, which it can't open on its own. Signing happens in the browser after a passkey unlock. | Browser apps that want the user to hold part of the key. |

<Callout title="Split custody is not full threshold MPC">
Swivy can't sign alone for a `split_custody` wallet: hosted signing returns `client_reconstruction_required`, and signing happens in the browser instead. Native mobile support for this mode is still being built.
</Callout>

## Policies: what each environment allows [#policies-what-each-environment-allows]

Every environment has a policy you set in the console or from your backend:

- **Auth and MFA:** which login methods are on, and when a second factor is required.
- **Wallet creation:** which chains get a wallet automatically at login.
- **Signing and export:** whether export and raw signing are allowed at all, and what needs a passkey.
- **Chains:** which networks exist, each with its RPC URL.
- **Sponsorship:** which networks you pay gas on.

Policy lives on the environment, not in your app code, so you can tighten it without shipping a new build.

## Intents: how things get signed and sent [#intents-how-things-get-signed-and-sent]

You don't hand Swivy a private key operation. You submit an **intent**: "send this transaction on `base-sepolia` from this account". Swivy checks it against policy, signs it, optionally sponsors gas, broadcasts it through the configured RPC, records the status and sends a webhook.

```ts
const intent = await swivy.createTransactionIntentAndWait({
  accountId: 'acct_...',
  chain: 'evm',                 // adapter family: 'evm' or 'solana'
  challengeId,                  // from a passkey step-up, if policy requires it
  payload: {
    network: 'base-sepolia',    // must match a network configured on the environment
    transaction: { to: '0x1111111111111111111111111111111111111111', value: '0x0', data: '0x' },
  },
});
console.log(intent.status, intent.result);
```

An intent moves through these statuses:

| Status | Meaning |
|---|---|
| `pending_step_up` | Policy needs a passkey (or other second factor) approval first. |
| `queued` | Accepted and waiting for the worker. |
| `processing` | Being signed, sponsored and broadcast. |
| `completed` | Done. `result` has the signature or transaction hash. |
| `failed` | Rejected or errored. The error explains why. |

Intent kinds are `sign_message`, `sign_digest`, `sign_typed_data`, `sign_transaction` and `execute_transaction`.

Use test networks such as `base-sepolia` and `solana-devnet` in the current preview, with RPC configured for each environment. The cumulative EVM profile uses `ethereum-sepolia`; see [delegated execution limits](/docs/swivy/delegated-limits). Mainnet adapter support does not establish production custody readiness.

## Step-up: approving with a passkey [#step-up-approving-with-a-passkey]

Login proves who someone is. **Step-up** proves they meant *this* action. Before a sensitive operation, your app creates a challenge, the user approves it with their passkey, and you attach the resulting `challengeId` to the intent.

```ts
const approval = await swivy.approveWithPasskey(passkeyAuthMethodId, 'intent_approval');
// attach approval.challenge.challengeId to the intent
```

Challenge purposes are `intent_approval`, `wallet_reconstruction` (the unlock before local signing in split custody), `account_export`, `session_delegation` (approving an agent grant) and `recovery`.
