Session key

Of the four things this catalogue's clients call a key, the session key is the only one designed to be handed to a bot. It is also the one whose name promises the wrong thing: "session" suggests something that ends when you close the window, and this one is good for six months.

How it works

The owner of a deposit wallet creates a fresh keypair somewhere they control — a server, a container, the machine the bot runs on — and asks Polymarket to authorise its public address. Polymarket's Python SDK is explicit about the division of labour: it receives only the public address, and the application remains responsible for generating, storing and protecting the private key. The authorisation is an on-chain transaction; the SDK call returns only after that transaction is confirmed and the key shows up in the wallet's list of active keys.

What the authorisation carries, as the SDK models it:

• Scopes, which name trading venues. The known values are CLOB for the order book, COMBOSRFQ for combination quotes, and ALL, documented as all current and future venues, which cannot be combined with anything else. Newer scope names are accepted as plain strings before the SDK learns them. None of the known scopes is a transfer or a withdrawal.
• An expiry. Authorisations expire 180 days after they are created, returned as a UTC timestamp.
• A way back. The owner can list active session keys and revoke any one of them; only the owner can list them, and revocation returns once the key is gone from the registry and unusable.

Two practical prerequisites come with it. Authorising needs a Builder API key passed to the client, and revoking needs an API key that supports gasless transactions. And the SDK does not yet do everything the scopes allow: its combination-quote code refuses to run under a session key even though a COMBOSRFQ scope exists.

The word used elsewhere

In security engineering a key made for one session is a short-lived thing. NIST's glossary defines an ephemeral key as one generated for each execution of a cryptographic process, unique to each message or session. The Polymarket usage shares the name and none of the lifetime. It also shares the vendor's own SDKs with a third meaning: the TypeScript SDK's changelog uses "session" for an authenticated Perps connection and for an RFQ quoter connection, neither of which is a key.

Why it matters here

The default scope is the widest one. If you authorise a key without naming scopes, the SDK asks for ALL, and ALL includes venues Polymarket has not launched yet. A bot that only posts to the order book should be given CLOB and nothing else; the narrowing is available only if you ask for it.

Revocable is not the same as short-lived. A copied session key keeps working for the rest of its 180 days unless someone notices and revokes it. The protection it buys is that the owner key, which controls the wallet, never has to sit on the machine the bot runs on. That is a real improvement over a bot holding the wallet key, and it is not a reason to store the session key carelessly: whoever holds it can trade the wallet's balance into positions.

The key that signed an order is not the person who decided it. Once delegation exists, an on-chain signature says which key acted, not which human or program chose the trade. For wallet analytics that is the reason a signer address is weak evidence of anything — what wallet tracking shows makes the same point about relayers.

Client support is uneven. polymarket-client ships authorisation, listing and revocation; the other three Python clients in the comparison of the four do not, which is one of the reasons that page comes out the way it does. Before building on a session key, check that the calls your bot needs — orders, cancels, combination quotes — are ones your library supports under one.

Read the vendor's own limits before you design around it. Polymarket's documentation of the feature, including what a session key can see of the owner's other activity and what it can never do with the balance, is walked through in where your key lives, which puts it beside the three other kinds of key a trading client asks for.