Server wallets, users & webhooks
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.
15 operations from the November 1, 2026 deployed contract. Full OpenAPI schema · Live interactive reference.
Create an app-owned server wallet (secret key only)
Any number of wallets per chain. idempotencyKey returns the same wallet on retry. An optional Ed25519 authorizationPublicKey makes every intent require a signature from the matching key.
Auth: x-swivy-app-id + x-swivy-secret-key
Request body: required. Server wallet
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Server wallet · 401 Missing or invalid secret key · 403 Publishable key used, or chain not allowed · 409 Idempotency key reused for a different chain
List server wallets
Auth: x-swivy-app-id + x-swivy-secret-key
Responses: 200 Server wallets · 401 Missing or invalid secret key
Fetch a server wallet
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
walletId | path | Yes | Server wallet identifier |
Responses: 200 Server wallet · 404 Server wallet not found
Queue a signing intent on a server wallet
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
walletId | path | Yes | Server wallet identifier |
Request body: required. Intent payload and optional authorization
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Intent · 401 Missing or invalid authorization signature · 403 Signing not allowed by environment policy · 409 Authorization nonce reused
Queue a transaction (sign and broadcast) on a server wallet
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
walletId | path | Yes | Server wallet identifier |
Request body: required. Intent payload and optional authorization
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Intent · 401 Missing or invalid authorization signature · 403 Execution not allowed by environment policy
Fetch a server-wallet intent
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
walletId | path | Yes | Server wallet identifier |
intentId | path | Yes | Intent identifier |
Responses: 200 Intent · 404 Intent not found
Create (or find by email) a user, optionally with wallets
Auth: x-swivy-app-id + x-swivy-secret-key
Request body: required. Email, externalUserId, createWallets
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 User · 400 Reserved email domain
Look up a user by email
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
email | query | Yes | User email |
Responses: 200 User with wallets and auth methods · 404 User not found
List users with their auth-method types and MFA posture
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
limit | query | No | Max rows (1-500) |
cursor | query | No | nextCursor from the previous page |
Responses: 200 Users page
Create a managed wallet for an existing user
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
userId | path | Yes | Identity identifier |
Request body: required. Chain and label
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Managed account · 403 Chain not allowed · 404 User not found
Fetch a user by id
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
userId | path | Yes | Identity identifier |
Responses: 200 User with wallets and auth methods · 404 User not found
Delete a user's personal data and access (wallets are kept)
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
userId | path | Yes | Identity identifier |
Responses: 200 Deleted · 404 User not found
Verify a user's session token from a backend
Auth: x-swivy-app-id + x-swivy-secret-key
Request body: required. Session token
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Session · 401 Invalid or expired session
List webhook deliveries and their retry state
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
status | query | No | pending, delivering, delivered or failed |
limit | query | No | Max rows (1-200) |
Responses: 200 Deliveries
Replay a failed or delivered webhook
Auth: x-swivy-app-id + x-swivy-secret-key
| Parameter | Location | Required | Description |
|---|---|---|---|
deliveryId | path | Yes | Delivery identifier |
Responses: 200 Delivery queued again · 404 No replayable delivery