Para Wallet

Create a Wallet

POST /v1/wallets

Creates a new MPC wallet for a user. Each combination of type + scheme + userIdentifier produces exactly one wallet. Attempting to create a duplicate returns a 409 with the existing walletId.

Request Body

EVM Example

curl -X POST https://api.beta.getpara.com/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{
    "type": "EVM",
    "userIdentifier": "[email protected]",
    "userIdentifierType": "EMAIL"
  }'

Solana Example

curl -X POST https://api.beta.getpara.com/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{
    "type": "SOLANA",
    "userIdentifier": "[email protected]",
    "userIdentifierType": "EMAIL"
  }'

Response (201 Created)

The wallet starts in creating status. You must poll until it reaches ready.

{
  "id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "type": "EVM",
  "scheme": "DKLS",
  "status": "creating",
  "createdAt": "2024-01-15T09:30:00Z"
}

The response includes a Location header with the wallet's URL:

Location: /v1/wallets/0a1b2c3d-4e5f-6789-abcd-ef0123456789

Polling for Ready Status

After creating a wallet, poll GET /v1/wallets/{walletId} until status becomes ready:

# Poll every 1 second until the wallet is ready
WALLET_ID="0a1b2c3d-4e5f-6789-abcd-ef0123456789"
while true; do
  RESPONSE=$(curl -s https://api.beta.getpara.com/v1/wallets/$WALLET_ID \
    -H "X-API-Key: $PARA_API_KEY")
  STATUS=$(echo "$RESPONSE" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  if [ "$STATUS" = "ready" ]; then
    echo "$RESPONSE"
    break
  fi
  sleep 1
done

Get Wallet Status

GET /v1/wallets/{walletId}

Retrieves the current status and details of a wallet.

Request

curl https://api.beta.getpara.com/v1/wallets/0a1b2c3d-4e5f-6789-abcd-ef0123456789 \
  -H "X-API-Key: $PARA_API_KEY"

Response (200 OK)

When the wallet is ready, the response includes the address and public key:

{
  "id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "type": "EVM",
  "scheme": "DKLS",
  "status": "ready",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "publicKey": "04a1b2c3d4e5f6...",
  "createdAt": "2024-01-15T09:30:00Z"
}

Response Fields

Sign Data

POST /v1/wallets/{walletId}/sign-raw

Signs arbitrary data using the wallet's MPC key shares. The private key is never assembled — each share signs independently and the results are combined.

Important: The wallet must be in ready status before signing.

Request Body

EVM Example

Sign a message hash (e.g., a keccak256 hash of a transaction):

curl -X POST https://api.beta.getpara.com/v1/wallets/0a1b2c3d-4e5f-6789-abcd-ef0123456789/sign-raw \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{
    "data": "0x48656c6c6f20576f726c64"
  }'

Solana Example

Sign a serialized Solana transaction:

curl -X POST https://api.beta.getpara.com/v1/wallets/aabbccdd-1122-3344-5566-778899aabbcc/sign-raw \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{
    "data": "0x01000103b5d..."
  }'

Response (200 OK)

{
  "signature": "a1b2c3d4e5f6..."
}

The signature is a hex string without the 0x prefix.

Key Concepts

Wallet Uniqueness

Each combination of type + scheme + userIdentifier maps to exactly one wallet. If you try to create a duplicate, the API returns 409 Conflict with the existing wallet's ID in the response body. Use this to safely retry or look up existing wallets.

Async Wallet Creation

Wallet creation is asynchronous. The POST /v1/wallets call returns immediately with status: "creating". You must poll GET /v1/wallets/{walletId} until status becomes "ready" before you can use the wallet to sign.

MPC Security Model

Para uses Multi-Party Computation so the full private key never exists on any single machine. Key shares are distributed across independent parties. When you call sign-raw, each party signs with their share and the results are combined into a valid signature. This means:

• No single point of compromise can leak the private key
• Agents can sign transactions without ever having access to a full key
• Signing is functionally equivalent to a normal signature from the blockchain's perspective

Error Reference

All error responses include a message field describing the issue.

409 Conflict Response

The 409 response includes the existing wallet's ID so you can retrieve it:

{
  "message": "a wallet for this identifier and type already exists",
  "walletId": "0a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

Complete Example: Create Wallet and Sign

# 1. Create an EVM wallet
RESPONSE=$(curl -s -X POST https://api.beta.getpara.com/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{
    "type": "EVM",
    "userIdentifier": "[email protected]",
    "userIdentifierType": "EMAIL"
  }')

WALLET_ID=$(echo "$RESPONSE" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
echo "Created wallet: $WALLET_ID"

# 2. Poll until ready
while true; do
  WALLET=$(curl -s https://api.beta.getpara.com/v1/wallets/$WALLET_ID \
    -H "X-API-Key: $PARA_API_KEY")
  STATUS=$(echo "$WALLET" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  if [ "$STATUS" = "ready" ]; then
    echo "Wallet is ready"
    echo "$WALLET"
    break
  fi
  echo "Status: $STATUS — waiting..."
  sleep 1
done

# 3. Sign data
SIGNATURE=$(curl -s -X POST https://api.beta.getpara.com/v1/wallets/$WALLET_ID/sign-raw \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARA_API_KEY" \
  -d '{"data": "0x48656c6c6f"}')

echo "Signature: $SIGNATURE"