Simmer Wallet Setup

Self-custody wallet setup for an agent that signs its own real-money trades on Polymarket or Kalshi. Three independent paths, pick one.

intent

set up self-custody signing for a Simmer agent so it can execute trades on Polymarket (Polygon) or Kalshi (Solana) without a browser session or managed wallet. path A uses OWS (local encrypted vault, recommended). path B uses a raw private key env var (legacy, fully supported). path C wires an existing dashboard-registered agent to your local runtime. skip this entire skill if you use a managed wallet (that's a dashboard flow, not an agent task).

inputs

external connections

• Simmer SDK API key (required)

  • env var: SIMMER_API_KEY
  • format: sk_live_* (must start with sk_live_)
  • source: simmer.markets/dashboard → Agent Settings → API Key
  • scopes: agent trading, wallet registration, approval signing
  • expiry: check dashboard for revocation / expiration dates
  • fallback: none (skill fails if missing)

• Open Wallet Standard (OWS) (required for Path A only)

  • tool: ows CLI, installed via curl script
  • vault location: ~/.ows/ (AES-256-GCM encrypted)
  • supported chains: EVM (Polygon, Base, Arbitrum), Solana
  • auth: local only, no external API key needed
  • rate limits: none (local operation)

• Polymarket CLOB (required for Polymarket trades)

  • endpoint: accessed via Simmer SDK proxy (no direct RPC needed)
  • collateral: pUSD (V2), USDC.e (legacy)
  • approval scope: all standard ERC-20 operations
  • network: Polygon (chain ID 137)

• Kalshi / Solana (required for Kalshi trades)

  • endpoint: Solana RPC
  • collateral: USDC
  • KYC: required via dflow.net/proof
  • network: Solana mainnet

context

• Python 3.10+ (required)
• pip package manager (required)
• Either an existing OWS wallet or a raw private key (depends on path)
• For Path C: dashboard-registered agent with API key and EOA private key
• For Polymarket: USDC or USDC.e on Polygon or Ethereum (need bridge to pUSD for V2)
• For Kalshi: SOL + USDC on Solana mainnet

prerequisites by path

Path	Prerequisites
Path A (OWS)	Python 3.10+, OWS CLI, SDK with [ows] extra, Elite tier for headless registration (dashboard path also works).
Path B (raw key)	Python 3.10+, SDK, Polygon wallet with private key (USDC.e or pUSD), any tier.
Path C (connect existing)	Python 3.10+, SDK with [ows] extra, OWS CLI, API key from dashboard, EOA private key from dashboard registration, existing agent in dashboard.

procedure

Path A: OWS per-agent wallet (recommended)

Step 1: Install OWS CLI and SDK

Input: bash shell, internet access, sudo or user write permissions to /usr/local/bin or $HOME/.local/bin

Procedure:

# install OWS CLI (creates ~/.ows vault directory, auto-initializes)
curl -fsSL https://docs.openwallet.sh/install.sh | bash

# reload shell to add ows to PATH
source ~/.bashrc  # or ~/.zshrc for zsh

# verify ows is in PATH
ows --version

# install Simmer SDK with OWS bindings [ows] extra is required
pip install 'simmer-sdk[ows]'

Output: OWS CLI binary installed, SDK with ows module available, ~/.ows vault directory created (empty)

Edge cases:

• If curl fails (network timeout, SSL error): check internet, retry with --insecure flag (not recommended for prod, security risk)
• If install script requires sudo: try bash -c "$(curl ...)" with --user flag if available
• If pip fails due to conflicting deps: use pip install --upgrade pip first, then retry

Step 2: Create a wallet in OWS

Input: OWS CLI installed, wallet name (alphanumeric + hyphens, e.g. "my-agent-wallet")

Procedure:

# create a new wallet (derives EVM + Solana addresses automatically)
ows wallet create --name "my-agent-wallet"

# show the wallet's addresses (need the EVM address for funding)
ows wallet show my-agent-wallet

Output: wallet created at ~/.ows/wallets/my-agent-wallet/ with:

• EVM address (Polygon + all EVM chains): 0x...
• Solana address (if multi-chain): relevant...
• encrypted private key (never exposed in plaintext)

Edge cases:

• if wallet name already exists: ows wallet create fails with "wallet exists". use a different name or delete first with ows wallet delete <name>
• if ~/.ows is corrupted: back it up, then rm -rf ~/.ows and reinstall OWS CLI (lost wallets cannot be recovered)
• if OWS vault password is forgotten: vault is lost, reinstall and create new wallet

Step 3: Fund the wallet

Input: EVM address from Step 2, USDC or USDC.e on Ethereum/Polygon/Base/Arbitrum, or SOL+USDC on Solana

Procedure (Polymarket on Polygon):

# from Step 2, copy the EVM address
EVM_ADDR="0x..."  # from ows wallet show output

# bridge USDC.e from Ethereum to Polygon via stargate / across / or exchange bridge
# or send USDC.e directly if you have it on Polygon already
# recipient: $EVM_ADDR
# amount: 10+ USDC.e recommended (gas buffer + trading capital)

# verify balance (check Polygonscan with $EVM_ADDR)
# example: https://polygonscan.com/address/0x...

Procedure (Kalshi on Solana):

# from Step 2, copy the Solana address
SOL_ADDR="..."  # from ows wallet show output

# send SOL + USDC to $SOL_ADDR (Solana mainnet, not testnet)
# amount: 0.5+ SOL (gas) + 10+ USDC recommended

# complete KYC at dflow.net/proof (required for Kalshi trading)

Output: wallet shows confirmed balance on-chain; Polygonscan / Solana Explorer reflects deposits

Edge cases:

• if gas fees are high: wait for network congestion to drop, or use a lower-fee bridge (across is often cheaper than stargate)
• if bridge sends to wrong chain: funds are stuck; contact bridge support or use a cross-chain swap tool
• if balance doesn't appear after 10 min: check tx hash, verify recipient address, wait for block finality (2-3 min on Polygon, 20s on Solana)

Step 4: Register the wallet with Simmer (Elite tier required for headless)

Input: SIMMER_API_KEY set, OWS wallet name from Step 2, wallet funded (Step 3), Python 3.10+ with simmer-sdk[ows]

Procedure:

# set API key in environment
export SIMMER_API_KEY="sk_live_..."  # from simmer.markets/dashboard

# register the wallet headlessly (requires Elite tier)
python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient(
    api_key="sk_live_...",  # or auto-read from $SIMMER_API_KEY if not passed
    ows_wallet="my-agent-wallet"
)

# one-time registration (Elite-only), fully headless, no browser needed
result = client.register_agent_wallet()
print(f"Registered: {result}")
EOF

Output: wallet registered server-side, agent can now sign trades

Conditions and edge cases:

• if API key is not Elite tier: call fails with "Account does not have Elite tier". fallback: register via dashboard instead (My Agents → Create agent → "Link dedicated wallet", or retrofit existing agent via Wallet tab)
• if OWS wallet name is wrong: call fails with "Wallet not found". verify with ows wallet list
• if OWS vault is locked (password required): OWS CLI prompts for password interactively
• if API key is expired or revoked: call fails with 401 Unauthorized. refresh key from dashboard

Step 5: Set approvals (one-time per chain)

Input: wallet registered (Step 4), OWS_WALLET env var set or ows_wallet param, SIMMER_API_KEY set

Procedure:

export OWS_WALLET="my-agent-wallet"
export SIMMER_API_KEY="sk_live_..."

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient.from_env()

# signs approval transactions locally via OWS, broadcasts via Simmer RPC
# one-time per chain (Polygon if Polymarket, Solana if Kalshi)
result = client.set_approvals()
print(f"Approvals set: {result}")
EOF

Output: approval transactions signed and broadcasted; result.all_set == True or result.message == "approvals already set"

Conditions:

• if Polymarket V2 migration is incomplete: all_set == False, must wrap USDC to pUSD first (see troubleshooting)
• if running for Kalshi: Solana approvals are set (no USDC allowance needed, Solana uses Program Derived Addresses)
• if gas fees spike: transaction may fail due to slippage; wait and retry

Step 6: Trade

Input: wallet registered, approvals set, OWS_WALLET and SIMMER_API_KEY env vars set, market_id for Polymarket or Kalshi

Procedure (Polymarket):

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient.from_env(venue="polymarket")

# SDK builds order, OWS signs locally, Simmer broadcasts
result = client.trade(
    market_id="0x123...",
    outcome="yes",
    amount=10.0,
    reasoning="based on my analysis"
)
print(f"Trade result: {result}")
EOF

Procedure (Kalshi):

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient.from_env(venue="kalshi")

# same API, OWS routes signing to Solana keypair
result = client.trade(
    market_id="USDEQ25",  # Kalshi market ID
    outcome="yes",
    amount=5.0,
    reasoning="bullish on USD strength"
)
print(f"Trade result: {result}")
EOF

Output: order placed on-chain, result object with order_id, status, fills (if any)

Edge cases:

• if order fails due to "insufficient balance": top up wallet (Step 3)
• if order fails due to "price limit exceeded": market moved, retry with fresh quote
• if signing times out: OWS vault may be locked or too large (rarely); retry
• if Simmer RPC times out: network issue, exponential backoff and retry

Step 7: Set up auto risk monitor (optional)

Input: simmer.markets/dashboard access, agent created

Procedure:

go to simmer.markets/dashboard → Settings → Auto Risk Monitor
configure stop-loss % and take-profit % for auto exits
save settings

Output: risk monitor rules stored server-side; SDK auto-executes exits on each get_briefing() cycle (agent must be running)

Note: no code changes needed, fully automatic

---

Path B: External raw key (legacy, fully supported)

Step 1: Set private key in environment

Input: Polygon EVM wallet private key (0x-prefixed hex), bash shell

Procedure:

# DON'T use pbpaste or pipe from clipboard ,  security risk (SIM-2118)
# use read -s to avoid echoing to terminal
read -s -p "Enter WALLET_PRIVATE_KEY: " WALLET_PRIVATE_KEY
export WALLET_PRIVATE_KEY

# or if key is already in a file:
export WALLET_PRIVATE_KEY=$(cat /path/to/key.txt)

# verify it's set (check first 20 chars to avoid printing full key)
echo "Key starts with: $(echo $WALLET_PRIVATE_KEY | cut -c1-20)"

Output: WALLET_PRIVATE_KEY env var set, accessible to Python process

Edge cases:

• if key includes leading/trailing whitespace: export WALLET_PRIVATE_KEY=$(echo -n "$WALLET_PRIVATE_KEY" | xargs) to trim
• if key is not 0x-prefixed: SDK adds prefix automatically
• if key is wrong format: SDK fails at first signing with "invalid key"

Step 2: Install SDK

Input: Python 3.10+, pip

Procedure:

pip install simmer-sdk

Output: SDK installed, no [ows] extra needed for this path

Step 3: Link wallet (one-time)

Input: WALLET_PRIVATE_KEY set, SIMMER_API_KEY set, Python 3.10+

Procedure:

export SIMMER_API_KEY="sk_live_..."
export WALLET_PRIVATE_KEY="0x..."

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

# signs a challenge message locally, fully headless, key never leaves agent
result = client.link_wallet()
print(f"Wallet linked: {result}")
EOF

Output: wallet linked server-side, agent authenticated for this key

Edge cases:

• if key doesn't match any on-chain account: call fails with "wallet not found"
• if key is already linked: call is idempotent, returns success

Step 4: Set approvals (one-time)

Input: wallet linked (Step 3), WALLET_PRIVATE_KEY and SIMMER_API_KEY set

Procedure:

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

# signs approval txs locally, broadcasts via Simmer RPC, key never leaves agent
result = client.set_approvals()
print(f"Approvals set: {result}")
EOF

Output: all_set=True (or already set), Polygon approval txs confirmed on-chain

Edge cases:

• if insufficient gas: add funds to wallet, retry
• if Polymarket on V2 and USDC.e stranded: see Step 5

Step 5: Activate Polymarket Deposit Wallet (if applicable)

Input: Elite or upgraded account, WALLET_PRIVATE_KEY set, approvals set (Step 4)

Procedure (only if your account has been upgraded to use Polymarket Deposit Wallet):

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

# one-time activation, signs EIP-712 batch headlessly
result = client.activate_polymarket_dw()
print(f"DW activated: {result}")
EOF

Output: Deposit Wallet activated, ready for trading

Conditions:

• skip this step if using standard Polymarket CLOB (non-DW account)
• if already activated: call is idempotent, returns immediately

Alternative: use dashboard (simmer.markets/dashboard → Wallets → Activate Trading) instead if you prefer browser flow

Step 6: Wrap stranded USDC.e (if applicable)

Input: USDC.e on Polymarket Deposit Wallet, WALLET_PRIVATE_KEY set, Deposit Wallet activated

Procedure:

python << 'EOF'
from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

# converts USDC.e to pUSD on Deposit Wallet, headless, idempotent
result = client.wrap_on_dw()
print(f"Wrap result: {result}")
# returns: {"wrapped": bool, "amount_units": int, "calls_count":