# Accounts & wallets (/docs/swivy/api-reference/accounts)

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

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

## Create or fetch a managed embedded account [#create-or-fetch-a-managed-embedded-account]

<EndpointHeader method="POST" path="/v1/runtime/accounts/managed" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

**Request body:** required. Managed account payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `chain` | string | Yes | Allowed: evm, solana |
| `purpose` | string | No | Allowed: agent, personal, recovery, treasury |
| `label` | string | No |  |
| `custodyMode` | string | No | Allowed: managed_tee, split_custody |
| `splitCustody` | object | No |  |
| `browserProvisioning` | object | No |  |

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

**Responses:** `200` Managed account resolution · `400` Invalid custody or browser provisioning payload · `401` Invalid runtime session or environment credentials · `403` Managed account creation not allowed

## List managed accounts and linked wallets [#list-managed-accounts-and-linked-wallets]

<EndpointHeader method="GET" path="/v1/runtime/accounts" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

**Responses:** `200` Managed accounts and linked wallets · `401` Invalid runtime session or environment credentials

## Get custody metadata for an account [#get-custody-metadata-for-an-account]

<EndpointHeader method="GET" path="/v1/runtime/accounts/{accountId}/custody" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Responses:** `200` Account custody metadata · `401` Invalid runtime session or environment credentials · `404` Managed account not found · `409` Client reconstruction required

## Fetch the server share for a browser-split wallet [#fetch-the-server-share-for-a-browser-split-wallet]

<EndpointHeader method="POST" path="/v1/runtime/accounts/{accountId}/custody/server-share" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Request body:** required. Verified MFA challenge used to unlock local reconstruction

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `challengeId` | string | Yes |  |

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

**Responses:** `200` Server share payload · `400` Missing challenge identifier · `401` Invalid runtime session or unverified MFA challenge · `404` Managed account or server share not found · `409` Server share not applicable

## Enable split custody metadata for an existing account [#enable-split-custody-metadata-for-an-existing-account]

<EndpointHeader method="POST" path="/v1/runtime/accounts/{accountId}/custody/split" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Request body:** required. Split custody metadata

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `deviceShare` | object | Yes |  |
| `recoveryShare` | object | No |  |

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

**Responses:** `200` Split custody enabled · `401` Invalid runtime session or environment credentials · `403` Split custody not allowed · `404` Managed account or owner not found

## Record a client-reported browser-local signing event [#record-a-client-reported-browser-local-signing-event]

<EndpointHeader method="POST" path="/v1/runtime/accounts/{accountId}/local-signing-events" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Request body:** required. Client-reported metadata for a browser-local signing flow

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `chain` | string | Yes | Allowed: evm, solana |
| `signingKind` | string | Yes | Allowed: message, typed_data, transaction |
| `challengeId` | string | No |  |
| `signerAddress` | string | No |  |
| `signerPublicKey` | string | No |  |
| `signedPayloadPresent` | boolean | No |  |
| `metadata` | object | No |  |

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

**Responses:** `200` Local signing audit event recorded · `401` Invalid runtime session or environment credentials · `404` Managed account not found · `409` Local signing audit not applicable

## Link an external wallet [#link-an-external-wallet]

<EndpointHeader method="POST" path="/v1/runtime/accounts/linked" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

**Request body:** required. Linked wallet payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `chain` | string | Yes | Allowed: evm, solana |
| `address` | string | Yes |  |
| `connectorType` | string | Yes |  |
| `metadata` | object | No |  |

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

**Responses:** `200` Linked wallet created · `401` Invalid runtime session or environment credentials · `403` Wallet linking not allowed

## Export a managed account private key [#export-a-managed-account-private-key]

<EndpointHeader method="POST" path="/v1/runtime/accounts/{accountId}/export" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Request body:** required. Account export payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `challengeId` | string | Yes |  |

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

**Responses:** `200` Exported private key · `401` Invalid MFA challenge or runtime session · `403` Account export not allowed · `404` Managed account or owner not found · `409` Client reconstruction required

## Execute a raw signing payload immediately [#execute-a-raw-signing-payload-immediately]

<EndpointHeader method="POST" path="/v1/runtime/accounts/{accountId}/raw-sign" base={false} />

**Auth:** `x-swivy-app-id` + `x-swivy-publishable-key` + `Authorization: Bearer token (BearerSession)` **or** `x-swivy-app-id` + `x-swivy-secret-key` + `Authorization: Bearer token (BearerSession)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `accountId` | path | Yes | Managed account identifier |

**Request body:** required. Raw signing payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `challengeId` | string | Yes |  |
| `payload` | object | Yes |  |

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

**Responses:** `200` Raw signing result · `400` Unsupported raw-sign payload · `401` Invalid MFA challenge or runtime session · `403` Raw signing not allowed · `404` Managed account or owner not found · `409` Client reconstruction required
