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

Accounts & wallets

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.

9 operations from the November 1, 2026 deployed contract. Full OpenAPI schema · Live interactive reference.

Create or fetch a managed embedded account

POST/v1/runtime/accounts/managed

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.

FieldTypeRequiredDescription
chainstringYesAllowed: evm, solana
purposestringNoAllowed: agent, personal, recovery, treasury
labelstringNo
custodyModestringNoAllowed: managed_tee, split_custody
splitCustodyobjectNo
browserProvisioningobjectNo

Nested schemas and constraints are in the OpenAPI document.

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

GET/v1/runtime/accounts

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/v1/runtime/accounts/{accountId}/custody

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
accountIdpathYesManaged 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

POST/v1/runtime/accounts/{accountId}/custody/server-share

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
accountIdpathYesManaged account identifier

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

Content type: application/json.

FieldTypeRequiredDescription
challengeIdstringYes

Nested schemas and constraints are in the OpenAPI document.

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

POST/v1/runtime/accounts/{accountId}/custody/split

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
accountIdpathYesManaged account identifier

Request body: required. Split custody metadata

Content type: application/json.

FieldTypeRequiredDescription
deviceShareobjectYes
recoveryShareobjectNo

Nested schemas and constraints are in the OpenAPI document.

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

POST/v1/runtime/accounts/{accountId}/local-signing-events

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
accountIdpathYesManaged account identifier

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

Content type: application/json.

FieldTypeRequiredDescription
chainstringYesAllowed: evm, solana
signingKindstringYesAllowed: message, typed_data, transaction
challengeIdstringNo
signerAddressstringNo
signerPublicKeystringNo
signedPayloadPresentbooleanNo
metadataobjectNo

Nested schemas and constraints are in the OpenAPI document.

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

POST/v1/runtime/accounts/linked

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.

FieldTypeRequiredDescription
chainstringYesAllowed: evm, solana
addressstringYes
connectorTypestringYes
metadataobjectNo

Nested schemas and constraints are in the OpenAPI document.

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

Export a managed account private key

POST/v1/runtime/accounts/{accountId}/export

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
accountIdpathYesManaged account identifier

Request body: required. Account export payload

Content type: application/json.

FieldTypeRequiredDescription
challengeIdstringYes

Nested schemas and constraints are in the OpenAPI document.

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

POST/v1/runtime/accounts/{accountId}/raw-sign

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
accountIdpathYesManaged account identifier

Request body: required. Raw signing payload

Content type: application/json.

FieldTypeRequiredDescription
challengeIdstringYes
payloadobjectYes

Nested schemas and constraints are in the OpenAPI document.

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

On this page