Server-Side Signing

Keystation is a lightweight signing service that loads your MPC key shares and participates in Sodot MPC ceremonies on the server. It replaces the Tholos mobile app as the user party, enabling fully programmatic transaction approval and signing for Flex vaults.

Note

Keystation only works with Flex vaults. Standard vaults require all signers to participate in a real-time ceremony and are not supported for server-side signing.

When to use server-side signing

• Automated treasury operations (scheduled transfers, payroll)
• Trading bots and DeFi strategies
• Backend services that need to sign on behalf of a vault member
• CI/CD pipelines that deploy or interact with smart contracts

Prerequisites

Before setting up Keystation, you need:

1. A Flex vault with your user as a signer
2. A Personal Access Token (PAT) — see Authentication
3. An MPC backup file exported from the Tholos mobile app
4. The decryption password you set when creating the backup

Caution

The backup file contains your encrypted MPC key shares. Keep it secure — anyone with the backup file and decryption password can participate in signing ceremonies as your user.

How it works

Keystation exposes two endpoints:

Endpoint	Purpose
POST /sign	Low-level MPC signing — signs a single hash using your key share
POST /flex-sign	Full Flex vault flow — approve, sign, and broadcast a transaction

The /flex-sign endpoint handles the complete Flex vault lifecycle:

1. Get a challenge from the Tholos API for the transaction
2. Sign the challenge and approve concurrently — Keystation signs the challenge using its EdDSA key share while the API verifies the approval
3. Check the threshold — if not enough approvals yet, return the current count
4. Initiate signing — request Sodot rooms for each unsigned transaction hash
5. Sign all hashes — sign using ECDSA or EdDSA depending on the chain
6. Broadcast — submit the signed transaction to the blockchain

Setup

1. Export your MPC backup from the Tholos mobile app. This produces a file containing your encrypted ECDSA and EdDSA key shares for the vault.

2. Place the backup file named backup in the Keystation working directory.

3. Configure environment variables:

   Variable	Required	Description
   DECRYPTION_PASSWORD	Yes	Password to decrypt the MPC backup file
   THOLOS_API_URL	For Flex	Tholos API base URL (https://api.tholos.app)
   THOLOS_API_TOKEN	For Flex	Your Personal Access Token (tholos_pat_...)
   TLS_CERT_FILE	No	TLS certificate file path (enables HTTPS)
   TLS_KEY_FILE	No	TLS key file path (enables HTTPS)
   AWS_SECRET_ARN	No	AWS Secrets Manager ARN for the password

   The decryption password is loaded from (in order): AWS Secrets Manager, a Docker secret at /run/secrets/decryption_password, or the DECRYPTION_PASSWORD environment variable.

4. Start Keystation:

   DECRYPTION_PASSWORD="your-password" \
   THOLOS_API_URL="https://api.tholos.app" \
   THOLOS_API_TOKEN="tholos_pat_your_token" \
   ./keystation

   Keystation starts on port 8080 (HTTP) or 443 (HTTPS if TLS is configured). The /flex-sign endpoint is only registered when both THOLOS_API_URL and THOLOS_API_TOKEN are set.

Approve and sign a Flex vault transaction

The /flex-sign endpoint handles transactions that already exist on the Tholos API. Create the transaction first using the Send a Transaction flow, then use Keystation to approve and sign it.

cURL

curl -X POST http://localhost:8080/flex-sign \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": 12345,
    "roomId": "abc123-room-id"
  }'

JavaScript

const response = await fetch("http://localhost:8080/flex-sign", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    transactionId: 12345,
    roomId: "abc123-room-id",
  }),
});
const result = await response.json();
console.log(result.status); // "approved" or "broadcast"

If the threshold is met, Keystation automatically signs and broadcasts:

{
  "status": "broadcast",
  "currentApprovals": 2,
  "approvalsRequired": 2,
  "transactionHash": "0x1234567890abcdef..."
}

If more approvals are needed, it returns the current count:

{
  "status": "approved",
  "currentApprovals": 1,
  "approvalsRequired": 2
}

Sign a raw hash

The /sign endpoint performs low-level MPC signing without interacting with the Tholos API. Use this when you need to sign arbitrary data as part of a custom workflow.

ECDSA

curl -X POST http://localhost:8080/sign \
  -H "Content-Type: application/json" \
  -d '{
    "unsignedHash": "32c0436983f80b26220bb3f266ce1bc1d73f589ce3ed1e0ea419f8e4b1787d1a",
    "signingScheme": "ECDSA",
    "sodotRoomID": "8e04ee8f5e085ce8ecca24fb67235e58"
  }'

ECDSA is used for EVM chains, Bitcoin, and TRON. The hash must be exactly 64 hex characters (32 bytes).

EdDSA

curl -X POST http://localhost:8080/sign \
  -H "Content-Type: application/json" \
  -d '{
    "unsignedHash": "a1b2c3d4e5f6...",
    "signingScheme": "EDDSA",
    "sodotRoomID": "8e04ee8f5e085ce8ecca24fb67235e58"
  }'

EdDSA is used for Solana, Cosmos, and SUI chains. The hash can be any length.

Note

The /sign endpoint only performs your side of the MPC ceremony. Another party must simultaneously participate in the same Sodot room for the signing to complete.

OpenAPI spec

Keystation auto-generates an OpenAPI specification with full request/response schemas:

• Spec: GET /openapi.json
• Interactive docs: GET /docs

Security considerations

• Run Keystation in a private network — it should not be publicly accessible
• Use TLS in production (TLS_CERT_FILE and TLS_KEY_FILE)
• Store the decryption password in AWS Secrets Manager or Docker secrets, not as a plaintext environment variable
• The PAT carries your account’s full permissions — restrict the token’s scope and set an expiration date
• Rotate your PAT regularly using the token rotation endpoint

Next steps

• Send a Transaction — create transactions to approve with Keystation
• Vaults — understand Flex vault architecture
• Authentication — manage Personal Access Tokens
• API Reference — browse all Tholos API endpoints