[Feature]: An API reference

[schwartzman]

What would you like the SDK to support?

Publish reference documentation for polymarket-client.

You already have everything needed to generate a reference

The package ships py.typed, __init__.py declares an explicit __all__, every model is annotated. pdoc, mkdocstrings, or Sphinx autodoc would produce a browsable reference in an afternoon, in CI, free, and keep it correct on every release.

This is not a resource problem, it's a decision.

Asks

• Publish an API reference generated from the type annotations — every public symbol in __all__.
• State the intended stability guarantees for 0.x.

Along the way...

• Correct the migration guide's Balance & Allowance section to name get_balance_allowance.
• Specify the /balance-allowance cache semantics: when it goes stale, what /update does, whether reads refresh it.

Why do you need this?

polymarket-client is on PyPI. It is the "official," "unified" Python SDK. It has no reference documentation of any kind. Not incomplete documentation — none.

The complete inventory:

• getting-started/python.md — a quickstart. Install, instantiate, list_markets, done.
• dev-tooling/python.md — the same content again.
• migrate-from-previous-sdks.md — a migration guide that migrates us to an undocumented surface.
• docs/ in this repo — one file, sdk-direction.md, a philosophy essay about your design values. You documented why the API feels good instead of what it is.
• examples/ — eleven scripts.

AsyncSecureClient alone exposes north of a hundred public methods. Eleven examples isn't coverage, it's a rounding error.

The pages that look like a reference are for a different library

/trading/clients/public, /l1, /l2, /builder are laid out exactly like SDK reference docs — per-method signatures, ResponseField tables, the works. They document py_clob_client_v2: different class, different method names (getOrderBook vs get_order_book), different return types. Anyone arriving from the migration guide walks straight into them and writes code against a library they aren't using.

Wrong docs cost more than absent ones.

Examples

1. The migration guide denies a method you ship. Its Balance & Allowance mapping — "SDK handles automatically during order placement; explicit calls not required" — implies the balance read is gone. AsyncSecureClient.get_balance_allowance() exists, public and typed, findable only in clients/async_secure.py, and only after I had designed workarounds for a removal that never happened. GET /balance-allowance has meanwhile vanished from the docs but for an incidental error-codes entry.

2. Balance-cache freshness is specified nowhere. The old ecosystem ran update-then-read because the CLOB's balance view goes stale. Nothing states whether the bare read is fresh, when the cache refreshes, or — per _internal/actions/orders/place.py — that the SDK calls /balance-allowance/update only inside placement failure-recovery. Anyone tracking real capital gets to reverse-engineer whether their balances silently rot.

3. A breaking response contract lives in one changelog bullet. Since 0.2.0, matched orders no longer guarantee transactions_hashes; wait_for_order_fill_settlement replaces it. The place-orders walkthrough still shows transactions_hashes with no caveat.

4. create()'s real signature appears in no document. credentials= (resume with stored L2 creds, skip the derive roundtrip), nonce=, environment= — absent from every Python page, which shows private_key and wallet and stops. That a plain EOA is a supported account type is inferable only from a signing-table footnote and a TypeScript enum.

The obvious objection, addressed

"Read the source, it's typed." That is what I am doing, because you left no alternative. I now know this SDK better than your documentation conveys, via tarball and grep def — the workflow you shipped to every integrator on the platform. Some of us are building systems where knowing whether place_limit_order signs and submits or merely signs is load-bearing, and we won't guess, or outsource the guess to a language model that will confidently invent a signature and let us find out in production with real capital.

You shipped a 0.2.0 to PyPI, pointed the migration guide at it, and called it official. Pick one: it's somehow still unfinished, in which case say so loudly and stop routing people to it, or it's really the official SDK, in which case document it like one.

Example API or additional context

# Reconstructed by reading src/polymarket/clients/async_secure.py.
# No document states any of the following.

@classmethod
async def create(
    cls,
    *,
    private_key: str,
    wallet: str | None = None,
    environment: Environment = PRODUCTION,   # undocumented
    credentials: ApiKeyCreds | None = None,  # undocumented — resume with stored L2 creds
    nonce: int = 0,                          # undocumented
    logger: logging.Logger | None = None,    # undocumented
) -> Self: ...

# The method the migration guide implies no longer exists:
async def get_balance_allowance(
    self, *, asset_type: AssetType, token_id: str | None = None
) -> BalanceAllowance: ...

[cesarenaldi]

@schwartzman I understand the rationale for an SDK reference. I see you are referencing many of the older docs pages, did you see if the new docs are of helps here? By any means is not the same as a generated reference doc, but some of the aspects you mentioned seems addressed by the new docs.

[schwartzman]

The explicit need is for a comprehensive and exhaustive reference, as I think was made clear in the initial report.

I referenced the other docs specifically to point out that they aren't relevant to the issue at hand.

[cesarenaldi]

Understood, I see the value in comprehensive SDK reference documentation. I’ve scheduled work on this, but I can’t provide an ETA yet.