Skip to main content
worm-sdk is Worm’s official Python client. This page covers how to install it, authenticate, and use it against the REST API documented in this reference.

GitHub

Source, examples, and issue tracker.

PyPI

pip install worm-sdk.

Features

  • Full coverage of the Worm REST API — markets, events, search, spot orders, margin, redeems, and account data
  • Typed responses with Pydantic models
  • HMAC authentication for private endpoints
  • Optional Solana wallet signing for order, margin, and redeem flows
  • Cursor-based pagination helpers (CursorPage)
  • HTTP/2 via httpx
Requirements: Python 3.10+

Installation

For wallet signing (orders, margin, redeems):
Install from source:

Quickstart (public data)

No credentials required:

Authentication

The SDK handles HMAC signing for you. Create API credentials once with a Solana wallet, then pass api_key and api_secret to the client.
SolanaWalletSigner accepts a base58 secret string, 128-character hex keypair, or raw 64-byte keypair bytes. You can also pass any object that implements SignerProtocol (Ledger, KMS, etc.). For the raw HTTP bootstrap flow, see Authentication.

Environment variables

The SDK examples read these when set:
Never expose API secrets or private keys in client-side code, browsers, or public repositories. Keep signing server-side only.

Client namespaces

WormClient exposes namespaced APIs that map to the REST endpoints documented in this reference:

Pagination

List methods return a CursorPage[T] with items, next_cursor, and limit:
See Pagination for per-endpoint defaults and cursor behavior.

Trading helpers

When a signer is configured, convenience methods combine draft → sign → submit in one call:
Spot CLOB only. client.orders.place targets non-margin markets. For leveraged positions, use client.margin helpers after calling Estimate margin position.
Complete scripts for markets, orders, margin, and redeems live in the examples/ directory on GitHub.

Error handling

Errors mirror the API error envelope: WormAPIError exposes error_code, slug, and message.

Configuration

After each request, inspect client.last_response for rate-limit headers and response metadata. See Rate limits.

Integration checklist

  • Prefer worm-sdk for Python services; use raw HTTP for other languages.
  • Base URL: https://api.worm.wtf
  • Parse the standard envelope (data, meta, error) on raw HTTP calls.
  • Paginate with limit + cursor / meta.next_cursor.
  • Retry 429 and transient 5xx with backoff; honor Retry-After and X-RateLimit-Reset.
  • Keep HMAC and wallet signing server-side only.

Next steps

Worm MCP

Use Worm from AI agents in Cursor, Claude, and other MCP clients.

Authentication

HMAC payload format and manual key bootstrap.

API introduction

Endpoint families and public vs authenticated behavior.