Accounts & wallets
Embedded (managed) wallets, linked wallets, custody, export and raw signing.
Preview: not generally available
Swivy runs in staging only. Paths and fields can change before general availability. There is no public base URL yet; preview partners get theirs with their credentials.
Wallets belong to the signed-in user. Export and raw signing are off unless your environment policy allows them, and need a step-up challenge.
9 endpoints, generated from Swivy's OpenAPI document (apps/api/src/openapi.ts).
Create or fetch a managed embedded account
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Managed account payload
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Request body: Verified MFA challenge used to unlock local reconstruction
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Request body: Split custody metadata
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Request body: Client-reported metadata for a browser-local signing flow
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Linked wallet payload
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Request body: Account export payload
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 <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Request body: Raw signing payload
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