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
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.
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
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
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
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.
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
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.
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
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.
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
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.
Responses: 200 Linked wallet created · 401 Invalid runtime session or environment credentials · 403 Wallet linking not allowed
Export a managed account private key
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.
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
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.
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