# Server wallets, users & webhooks (/docs/swivy/api-reference/server)

<Callout type="warn" title="Testnet preview">
Staging uses software custody. Use your environment’s API base URL and test assets only.
</Callout>

15 operations from the November 1, 2026 deployed contract. [Full OpenAPI schema](/swivy/openapi.json) · [Live interactive reference](https://swivy.swopme.co/docs#reference).

## Create an app-owned server wallet (secret key only) [#create-an-app-owned-server-wallet-secret-key-only]

<EndpointHeader method="POST" path="/v1/server/wallets" base={false} />

Any number of wallets per chain. `idempotencyKey` returns the same wallet on retry. An optional Ed25519 `authorizationPublicKey` makes every intent require a signature from the matching key.

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

**Request body:** required. Server wallet

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Server wallet · `401` Missing or invalid secret key · `403` Publishable key used, or chain not allowed · `409` Idempotency key reused for a different chain

## List server wallets [#list-server-wallets]

<EndpointHeader method="GET" path="/v1/server/wallets" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

**Responses:** `200` Server wallets · `401` Missing or invalid secret key

## Fetch a server wallet [#fetch-a-server-wallet]

<EndpointHeader method="GET" path="/v1/server/wallets/{walletId}" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `walletId` | path | Yes | Server wallet identifier |

**Responses:** `200` Server wallet · `404` Server wallet not found

## Queue a signing intent on a server wallet [#queue-a-signing-intent-on-a-server-wallet]

<EndpointHeader method="POST" path="/v1/server/wallets/{walletId}/intents/signing" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `walletId` | path | Yes | Server wallet identifier |

**Request body:** required. Intent payload and optional authorization

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Intent · `401` Missing or invalid authorization signature · `403` Signing not allowed by environment policy · `409` Authorization nonce reused

## Queue a transaction (sign and broadcast) on a server wallet [#queue-a-transaction-sign-and-broadcast-on-a-server-wallet]

<EndpointHeader method="POST" path="/v1/server/wallets/{walletId}/intents/transactions" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `walletId` | path | Yes | Server wallet identifier |

**Request body:** required. Intent payload and optional authorization

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Intent · `401` Missing or invalid authorization signature · `403` Execution not allowed by environment policy

## Fetch a server-wallet intent [#fetch-a-server-wallet-intent]

<EndpointHeader method="GET" path="/v1/server/wallets/{walletId}/intents/{intentId}" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `walletId` | path | Yes | Server wallet identifier |
| `intentId` | path | Yes | Intent identifier |

**Responses:** `200` Intent · `404` Intent not found

## Create (or find by email) a user, optionally with wallets [#create-or-find-by-email-a-user-optionally-with-wallets]

<EndpointHeader method="POST" path="/v1/server/users" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

**Request body:** required. Email, externalUserId, createWallets

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` User · `400` Reserved email domain

## Look up a user by email [#look-up-a-user-by-email]

<EndpointHeader method="GET" path="/v1/server/users" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `email` | query | Yes | User email |

**Responses:** `200` User with wallets and auth methods · `404` User not found

## List users with their auth-method types and MFA posture [#list-users-with-their-auth-method-types-and-mfa-posture]

<EndpointHeader method="GET" path="/v1/server/users/list" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `limit` | query | No | Max rows (1-500) |
| `cursor` | query | No | nextCursor from the previous page |

**Responses:** `200` Users page

## Create a managed wallet for an existing user [#create-a-managed-wallet-for-an-existing-user]

<EndpointHeader method="POST" path="/v1/server/users/{userId}/wallets" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `userId` | path | Yes | Identity identifier |

**Request body:** required. Chain and label

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Managed account · `403` Chain not allowed · `404` User not found

## Fetch a user by id [#fetch-a-user-by-id]

<EndpointHeader method="GET" path="/v1/server/users/{userId}" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `userId` | path | Yes | Identity identifier |

**Responses:** `200` User with wallets and auth methods · `404` User not found

## Delete a user's personal data and access (wallets are kept) [#delete-a-users-personal-data-and-access-wallets-are-kept]

<EndpointHeader method="DELETE" path="/v1/server/users/{userId}" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `userId` | path | Yes | Identity identifier |

**Responses:** `200` Deleted · `404` User not found

## Verify a user's session token from a backend [#verify-a-users-session-token-from-a-backend]

<EndpointHeader method="POST" path="/v1/server/sessions/verify" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

**Request body:** required. Session token

Content type: `application/json`.

See the full schema for this payload; the contract does not enumerate top-level fields here.

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Session · `401` Invalid or expired session

## List webhook deliveries and their retry state [#list-webhook-deliveries-and-their-retry-state]

<EndpointHeader method="GET" path="/v1/server/webhooks/deliveries" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `status` | query | No | pending, delivering, delivered or failed |
| `limit` | query | No | Max rows (1-200) |

**Responses:** `200` Deliveries

## Replay a failed or delivered webhook [#replay-a-failed-or-delivered-webhook]

<EndpointHeader method="POST" path="/v1/server/webhooks/deliveries/{deliveryId}/replay" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-secret-key`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `deliveryId` | path | Yes | Delivery identifier |

**Responses:** `200` Delivery queued again · `404` No replayable delivery
