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

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)

POST/v1/server/wallets

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

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

GET/v1/server/wallets/{walletId}

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
walletIdpathYesServer wallet identifier

Responses: 200 Server wallet · 404 Server wallet not found

Queue a signing intent on a server wallet

POST/v1/server/wallets/{walletId}/intents/signing

Auth: x-swivy-app-id + x-swivy-secret-key

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

POST/v1/server/wallets/{walletId}/intents/transactions

Auth: x-swivy-app-id + x-swivy-secret-key

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

GET/v1/server/wallets/{walletId}/intents/{intentId}

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
walletIdpathYesServer wallet identifier
intentIdpathYesIntent identifier

Responses: 200 Intent · 404 Intent not found

Create (or find by email) a user, optionally with wallets

POST/v1/server/users

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

GET/v1/server/users

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
emailqueryYesUser email

Responses: 200 User with wallets and auth methods · 404 User not found

List users with their auth-method types and MFA posture

GET/v1/server/users/list

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
limitqueryNoMax rows (1-500)
cursorqueryNonextCursor from the previous page

Responses: 200 Users page

Create a managed wallet for an existing user

POST/v1/server/users/{userId}/wallets

Auth: x-swivy-app-id + x-swivy-secret-key

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

GET/v1/server/users/{userId}

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
userIdpathYesIdentity identifier

Responses: 200 User with wallets and auth methods · 404 User not found

Delete a user's personal data and access (wallets are kept)

DELETE/v1/server/users/{userId}

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
userIdpathYesIdentity identifier

Responses: 200 Deleted · 404 User not found

Verify a user's session token from a backend

POST/v1/server/sessions/verify

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

GET/v1/server/webhooks/deliveries

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
statusqueryNopending, delivering, delivered or failed
limitqueryNoMax rows (1-200)

Responses: 200 Deliveries

Replay a failed or delivered webhook

POST/v1/server/webhooks/deliveries/{deliveryId}/replay

Auth: x-swivy-app-id + x-swivy-secret-key

ParameterLocationRequiredDescription
deliveryIdpathYesDelivery identifier

Responses: 200 Delivery queued again · 404 No replayable delivery

On this page