docs
Get startedTroubleshootingPaymentsWebhooksAgent paymentsSwop MCPOviIdentity (swop.id)SwivyRPC (preview)API reference
API reference

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

GET/openapi.json

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

Responses: 200 OpenAPI document

Get deployment health summary

GET/health

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

Responses: 200 Service health

Get serving readiness status

GET/ready

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/deployment/readiness

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

GET/v1/runtime/chains/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

GET/v1/runtime/config

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/v1/runtime/me

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

POST/v1/runtime/id/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.

FieldTypeRequiredDescription
usernamestringYes

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

GET/v1/runtime/id/{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)

ParameterLocationRequiredDescription
usernamepathYesSwivy username

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

Start TOTP enrollment

POST/v1/runtime/mfa/totp/start

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.

FieldTypeRequiredDescription
labelstringNo

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

POST/v1/runtime/mfa/totp/verify

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.

FieldTypeRequiredDescription
authMethodIdstringYes
codestringYes

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

POST/v1/runtime/mfa/passkeys/register/start

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.

FieldTypeRequiredDescription
labelstringNo

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

POST/v1/runtime/mfa/passkeys/register/finish

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.

FieldTypeRequiredDescription
authMethodIdstringYes
challengeIdstringYes
registrationResponseobjectYes

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

POST/v1/runtime/mfa/passkeys

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.

FieldTypeRequiredDescription
labelstringYes
credentialIdstringYes
publicKeyPemstringYes

Nested schemas and constraints are in the OpenAPI document.

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

Start SMS MFA enrollment

POST/v1/runtime/mfa/sms/start

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.

FieldTypeRequiredDescription
labelstringNo
phoneNumberstringYes

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

POST/v1/runtime/mfa/sms/verify

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.

FieldTypeRequiredDescription
authMethodIdstringYes
challengeIdstringYes
codestringYes

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

POST/v1/runtime/mfa/challenges

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.

FieldTypeRequiredDescription
authMethodIdstringYes
purposestringYesAllowed: 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

POST/v1/runtime/mfa/challenges/verify

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.

FieldTypeRequiredDescription
challengeIdstringYes
codestringNo
signatureBase64stringNo
authenticationResponseobjectNo

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

GET/v1/mcp/{appId}/accounts

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

Auth: Authorization: Bearer token (McpAccessToken)

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

POST/v1/mcp/{appId}/accounts

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)

ParameterLocationRequiredDescription
appIdpathYesPinned issuer app identifier

Request body: required. Permitted wallet chain

Content type: application/json.

FieldTypeRequiredDescription
chainstringYesAllowed: 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

On this page