# System & capabilities (/docs/swivy/api-reference/system)

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

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

## Fetch the OpenAPI document [#fetch-the-openapi-document]

<EndpointHeader method="GET" path="/openapi.json" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

**Responses:** `200` OpenAPI document

## Get deployment health summary [#get-deployment-health-summary]

<EndpointHeader method="GET" path="/health" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

**Responses:** `200` Service health

## Get serving readiness status [#get-serving-readiness-status]

<EndpointHeader method="GET" path="/ready" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

**Responses:** `200` Service is ready · `503` Service dependencies are not ready

## Get launch readiness status [#get-launch-readiness-status]

<EndpointHeader method="GET" path="/deployment/readiness" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

**Responses:** `200` Deployment is launch ready · `503` Deployment launch checks are not ready

## List runtime chain capabilities [#list-runtime-chain-capabilities]

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

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

**Responses:** `200` Capabilities

## Get public runtime auth and signup configuration for the current environment [#get-public-runtime-auth-and-signup-configuration-for-the-current-environment]

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

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

**Responses:** `200` Runtime auth configuration · `401` Missing or invalid environment credentials

## Get the current runtime profile [#get-the-current-runtime-profile]

<EndpointHeader method="GET" path="/v1/runtime/me" 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` Runtime profile · `401` Invalid runtime session or environment credentials

## Claim or update the current runtime user's Swivy username [#claim-or-update-the-current-runtime-users-swivy-username]

<EndpointHeader method="POST" path="/v1/runtime/id/username" 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. Username claim payload

Content type: `application/json`.

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

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

**Responses:** `200` Username claimed · `400` Invalid or reserved username · `401` Invalid runtime session or environment credentials · `409` Username already taken

## Look up a Swivy username in the current project [#look-up-a-swivy-username-in-the-current-project]

<EndpointHeader method="GET" path="/v1/runtime/id/{username}" 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 |
|---|---|---|---|
| `username` | path | Yes | Swivy username |

**Responses:** `200` Swivy username lookup · `401` Invalid runtime session or environment credentials · `404` Username not found

## Start TOTP enrollment [#start-totp-enrollment]

<EndpointHeader method="POST" path="/v1/runtime/mfa/totp/start" 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:** optional. TOTP enrollment payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | No |  |

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

**Responses:** `200` TOTP enrollment created · `401` Invalid runtime session or environment credentials

## Verify a TOTP enrollment code [#verify-a-totp-enrollment-code]

<EndpointHeader method="POST" path="/v1/runtime/mfa/totp/verify" 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. TOTP verification payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `authMethodId` | string | Yes |  |
| `code` | string | Yes |  |

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

**Responses:** `200` TOTP verified · `401` Invalid TOTP code or runtime session · `404` Auth method not found

## Start passkey registration [#start-passkey-registration]

<EndpointHeader method="POST" path="/v1/runtime/mfa/passkeys/register/start" 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:** optional. Passkey registration payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | No |  |

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

**Responses:** `200` Passkey registration challenge and options · `401` Invalid runtime session or environment credentials · `404` Identity not found

## Finish passkey registration [#finish-passkey-registration]

<EndpointHeader method="POST" path="/v1/runtime/mfa/passkeys/register/finish" 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. Passkey registration verification payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `authMethodId` | string | Yes |  |
| `challengeId` | string | Yes |  |
| `registrationResponse` | object | Yes |  |

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

**Responses:** `200` Passkey registration completed · `401` Invalid passkey registration · `404` Challenge or auth method not found · `409` Passkey already registered

## Import a passkey public key directly [#import-a-passkey-public-key-directly]

<EndpointHeader method="POST" path="/v1/runtime/mfa/passkeys" 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. Direct passkey import payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | Yes |  |
| `credentialId` | string | Yes |  |
| `publicKeyPem` | string | Yes |  |

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

**Responses:** `200` Passkey created · `401` Invalid runtime session or environment credentials

## Start SMS MFA enrollment [#start-sms-mfa-enrollment]

<EndpointHeader method="POST" path="/v1/runtime/mfa/sms/start" 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. SMS enrollment payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string | No |  |
| `phoneNumber` | string | Yes |  |

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

**Responses:** `200` SMS enrollment created · `401` Invalid runtime session or environment credentials · `502` SMS delivery failed

## Verify an SMS enrollment code [#verify-an-sms-enrollment-code]

<EndpointHeader method="POST" path="/v1/runtime/mfa/sms/verify" 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. SMS verification payload

Content type: `application/json`.

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

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

**Responses:** `200` SMS verified · `401` Invalid SMS code or runtime session · `404` Challenge or auth method not found

## Create a step-up challenge [#create-a-step-up-challenge]

<EndpointHeader method="POST" path="/v1/runtime/mfa/challenges" 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. MFA challenge payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `authMethodId` | string | Yes |  |
| `purpose` | string | Yes | Allowed: account_export, intent_approval, recovery, session_delegation, wallet_reconstruction |

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

**Responses:** `200` Challenge created · `400` Challenge could not be created · `401` Invalid runtime session or environment credentials · `404` Active auth method not found · `502` SMS delivery failed

## Verify a step-up challenge [#verify-a-step-up-challenge]

<EndpointHeader method="POST" path="/v1/runtime/mfa/challenges/verify" 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. Challenge verification payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `challengeId` | string | Yes |  |
| `code` | string | No |  |
| `signatureBase64` | string | No |  |
| `authenticationResponse` | object | No |  |

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

**Responses:** `200` Challenge verified · `400` Missing passkey assertion · `401` Invalid verification code or signature · `404` Challenge or auth method not found

## List the signed-in MCP subject's wallets [#list-the-signed-in-mcp-subjects-wallets]

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

Requires wallets.read and owner-approved OAuth consent; returns public account fields only.

**Auth:** `Authorization: Bearer token (McpAccessToken)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Pinned issuer app identifier |

**Responses:** `200` Wallets · `401` Invalid or revoked session/token · `403` Insufficient scope or consent

## Create or reuse the signed-in MCP subject's agent wallet [#create-or-reuse-the-signed-in-mcp-subjects-agent-wallet]

<EndpointHeader method="POST" path="/v1/mcp/{appId}/accounts" base={false} />

Requires wallets.read plus wallets.create approved through OAuth consent. Honors chain/custody policy; grants no signing or export access.

**Auth:** `Authorization: Bearer token (McpAccessToken)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Pinned issuer app identifier |

**Request body:** required. Permitted wallet chain

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `chain` | string | Yes | Allowed: evm, solana |

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

**Responses:** `200` Created or existing public wallet · `400` Invalid request · `401` Invalid or revoked session/token · `403` Insufficient permission or policy · `409` Provisioning in progress; retry after the indicated delay
