System & capabilities
Current Swivy API operations from the deployed OpenAPI snapshot.
Testnet preview
Staging uses software custody. Use your environment’s API base URL and test assets only.
20 operations from the November 1, 2026 deployed contract. Full OpenAPI schema · Live interactive reference.
Fetch the OpenAPI document
Auth: No operation-level credentials specified; deployment and policy restrictions still apply.
Responses: 200 OpenAPI document
Get deployment health summary
Auth: No operation-level credentials specified; deployment and policy restrictions still apply.
Responses: 200 Service health
Get serving readiness status
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
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
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
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
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
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.
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
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
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.
Responses: 200 TOTP enrollment created · 401 Invalid runtime session or environment credentials
Verify a TOTP enrollment code
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.
Responses: 200 TOTP verified · 401 Invalid TOTP code or runtime session · 404 Auth method not found
Start passkey registration
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.
Responses: 200 Passkey registration challenge and options · 401 Invalid runtime session or environment credentials · 404 Identity not found
Finish passkey registration
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.
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
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.
Responses: 200 Passkey created · 401 Invalid runtime session or environment credentials
Start SMS MFA enrollment
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.
Responses: 200 SMS enrollment created · 401 Invalid runtime session or environment credentials · 502 SMS delivery failed
Verify an SMS enrollment code
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.
Responses: 200 SMS verified · 401 Invalid SMS code or runtime session · 404 Challenge or auth method not found
Create a step-up challenge
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.
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
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.
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
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
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.
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