​

Runbook: Session Key setup

Use this runbook to create the key that sesame uses to read your Polymarket account and to trade. The key is a Polymarket Session Key: it can place and cancel orders for your Deposit Wallet, but it is not the account’s owner key. The owner key never goes into this app. For combos, the key also needs the combos scope (section 8). The words this page uses are in the deploy guide’s Words used in these pages. Each setting is in the configuration reference. Background: Polymarket venue notes §10, secrets and logging policy, ADR 0009 and ADR 0012. Official Polymarket documentation:

• Session Keys: https://docs.polymarket.com/trading/session-keys
• Wallets and authentication: https://docs.polymarket.com/trading/wallets-auth
• API authentication: https://docs.polymarket.com/getting-started/api

​

1. Before you start

You need these things: Session Keys are in beta. Polymarket can change the steps. Read the official page before each rotation. CAUTION: Do not put the Session Key on the development server. That server is in a blocked location (security finding F8). Development there uses the fake venue (task dev:fake). What a Session Key can and cannot do:

​

2. Create the key

​

2.1 Make the key pair on the app host

1. On the app host, make a new key pair. Any standard tool can do this. With Foundry, type:
   cast wallet new
   
   The command shows an address and a private key.
2. Keep the private key on the app host. You need it in section 3.
3. Copy only the address to the owner machine.

WARNING: Do not paste the private key into a chat, an email, a pull request, a ticket or an AI agent session. If you must make the key pair on another machine, move the private key over an encrypted connection. Then delete the copy.

​

2.2 Authorise the key from the owner machine

1. On the owner machine, use the official TypeScript SDK (@polymarket/client) or the Python SDK (polymarket). With the TypeScript SDK, run this code:
   import { createSecureClient, SessionKeyKnownScope } from "@polymarket/client";
   import { builderApiKey } from "@polymarket/client/node";
   import { privateKey } from "@polymarket/client/viem";
   
   const secureClient = await createSecureClient({
     signer: privateKey(process.env.OWNER_PRIVATE_KEY),   // the owner key, on this machine only
     wallet: process.env.DEPOSIT_WALLET,                   // the Deposit Wallet address
     apiKey: builderApiKey({
       key: process.env.BUILDER_API_KEY,
       secret: process.env.BUILDER_SECRET,
       passphrase: process.env.BUILDER_PASSPHRASE,
     }),
   });
   
   await secureClient.authorizeSessionKey({
     address: "<session key address from 2.1>",
     scopes: [SessionKeyKnownScope.CLOB],
   });
   
2. Write down the expiry date: 180 days from today. You must rotate the key before that date (section 5).

• Always give scopes. If you do not, the SDK uses ALL.
• Without combos, give CLOB only. For combos, give CLOB and COMBOSRFQ, not ALL (section 8). ALL also covers each venue Polymarket adds later (security finding P8-11).
• The key works when it is in the wallet’s list of session signers. The SDK waits for this.
• The environment variable names in the code are for the owner machine only. Never put the owner key or the Builder API key in this app’s settings.

​

3. Configure the app

1. On the server, open the settings file:
   sudoedit /opt/sesame/sesame.env
   
2. Add these lines, with your values:
   POLYMARKET_WALLET_ADDRESS=<Deposit Wallet address>
   POLYMARKET_SESSION_KEY=<Session Key private key>
   POLYMARKET_OWNER_ADDRESS=<owner address>
   
3. Save the file and close the editor.
4. On your computer, restart the app:
   task deploy:start
   
   The command ends with a table that lists the sesame and caddy services.
5. Do the checks in section 4.

In development, put the same lines in the .env file in the repository root. Make the file readable only by the account that runs the app: mode 0600 on Linux, or icacls on Windows. The deploy guide gives the full go-live steps in Go live, step 3.

• Leave the three POLYMARKET_CLOB_* settings empty. At each start, the app makes the CLOB API credentials from the Session Key. It keeps them in memory only, never on disk, in the database or in the log (ADR 0009). If you set them, the app uses them and makes none. Set all three or none.
• The old name is refused. If the file has a POLYMARKET_PRIVATE_KEY line, even an empty one, the app does not start. Rename it to POLYMARKET_SESSION_KEY. Make sure that the value is a Session Key, not the owner key.
• Other refused lines. The app also does not start with GEOBLOCK_URL, or with a name that starts with POLYMARKET_RELAYER_, POLYMARKET_BRIDGE_URL, POLY_BUILDER_ or POLYMARKET_BUILDER_. The Builder API key stays on the owner machine.

What the app shows with each set of settings:

​

4. Check that it worked

1. The app starts. If a setting is wrong, the app does not start and its log names the setting. The log never shows the key. The app stops when:
   • the Session Key is not 64 hex characters, with or without 0x, or is not a valid private key
   • an address is not 40 hex characters, with or without 0x
   • the Session Key’s address, POLYMARKET_SIGNER_ADDRESS or the wallet address is the same as POLYMARKET_OWNER_ADDRESS
   • the wallet address is the same as the Session Key’s address
   • a Session Key or CLOB credentials are set without POLYMARKET_WALLET_ADDRESS
   • only some of the three POLYMARKET_CLOB_* settings are set, or a refused line is in the file
   What to do for each message is in deploy troubleshooting.
2. The start log confirms the key. On your computer, read the log:
   task deploy:logs
   
   Find the line session key confirmed. Its signer field is the Session Key’s address. Its validUntil field is the expiry. Its scopes field lists the scopes, for example CLOB.
3. Settings shows the account. In the app, open Settings > Account. Make sure that:
   • Credentials shows Connected
   • Signer address (Session Key) is the address from step 2.1, not the owner’s address
   • Wallet address (Deposit Wallet) is the Deposit Wallet address
   The Credentials row shows one of these:

   Label	Meaning
   Connected	The credentials are ready and the last call with them worked
   Connecting	The app makes the credentials now. The tooltip says Account credentials pending
   Account error	The credentials failed. The tooltip says Account credentials failed: <reason>. See section 7
   Read-only	The wallet address is set, but no Session Key. Positions show, cash and orders do not
   Not connected	No wallet address is set

   The top bar shows the same label beside Cash when the state is not Connected.
4. The figures match. Compare the top bar with polymarket.com:
   • Positions and cash must be the same.
   • The app shows only the orders that this Session Key placed. Orders placed on polymarket.com do not show in the app.

​

5. Rotation

Rotate the key before its 180 days end. Rotate it at once if the key may be exposed: in a log, a commit, a screenshot, a chat or an agent session, or on a host that may be compromised.

1. Make a new key pair on the app host (2.1).
2. Authorise it from the owner machine (2.2).
3. Put the new key in POLYMARKET_SESSION_KEY (section 3).
4. If you set the POLYMARKET_CLOB_* settings, clear them. They belong to the old key.
5. Restart the app.
6. Make sure that Settings > Account shows the new signer address and Connected (section 4).
7. Revoke the old key from the owner machine (section 6).

CAUTION: Revocation cancels the open orders of the old key. Do step 7 only when that is acceptable. The CLOB credentials need no rotation of their own. They belong to the Session Key and the app makes them again at each start. How the app shows the expiry:

​

6. Revocation

1. On the owner machine, use the same SDK client as in step 2.2:
   await secureClient.revokeSessionKey({ address: "<session key address>" });
   
2. Wait for the call to return. The key is then not active.

• Revocation stops the key from trading and cancels its open orders. It does not change the orders of other Session Keys or of the owner.
• Polymarket finishes the cancels and the on-chain step after the call returns.
• After revocation, the app’s next call with the credentials gets status 401. The app then checks its clock and tries to make new credentials. When that fails, the credentials show Account error with auth_rejected. If the clock is more than 2 seconds wrong, the reason is clock_skew.

If the Session Key or the host may be compromised, do these steps at once:

1. In the app, click Cancel all.
2. Set the switch to Safe.
3. Set LIVE_TRADING=false in the settings file and restart the app.
4. Revoke the Session Key from the owner machine (step 1 above). It is not enough to revoke the CLOB credentials, because the key can make new ones. The key may be able to move funds (ADR 0012). If the relayer is not available, use the owner-only emergency path in ADR 0012: pause, wait one hour, then revoke.
5. On polymarket.com, look for trades in your positions and history that the app did not make.
6. Follow the compromise steps in the secrets and logging policy.

​

7. Troubleshooting

When the credentials fail, Settings > Account shows Account credentials failed: <reason>. The reason is a fixed code. Polymarket’s own error text goes only to the app’s log. For wallet_mismatch:

1. Make sure that POLYMARKET_WALLET_ADDRESS is the Deposit Wallet that you authorised the key for in step 2.2.
2. Make sure that the key has the CLOB or ALL scope and that you did not revoke it. A key with COMBOSRFQ alone gives this reason, because the app needs CLOB too.
3. Make sure that the key is not expired. If it is, make a new key (section 5).
4. Read the log for session signers listed for another wallet. If you find it, Polymarket answered for another wallet. Its wallet and venueWallet fields show the two addresses, with only the first 6 and last 4 characters. Either POLYMARKET_WALLET_ADDRESS holds another address, such as the owner’s, or you authorised the key for another account.

Other problems:

​

8. Combos scope

Combos get quotes from Polymarket’s market makers. To accept a quote, the app signs an order. The app sends these requests with the Session Key’s credentials. Polymarket accepts them only from a key with the COMBOSRFQ or ALL scope (ADR 0014). A key with CLOB alone can still trade other markets, but combos stay off.

​

8.1 How a CLOB-only key shows

The app reads the scopes from Polymarket when it starts. After you change the key, restart the app.

​

8.2 Issue a key with the combos scope

This makes a new key, then revokes the old one, as in a rotation (section 5).

1. In the app, click Cancel all.
2. Set the switch to Safe.
3. On polymarket.com, make sure that no order from the app is still open. The new key cannot see the orders of the old key, and revocation cancels them.
4. Make a new key pair on the app host (2.1).
5. On the owner machine, authorise it with the same client as in step 2.2, with both scopes:
   await secureClient.authorizeSessionKey({
     address: "<new session key address>",
     scopes: [SessionKeyKnownScope.CLOB, SessionKeyKnownScope.COMBOSRFQ],
   });
   
6. Put the new key in POLYMARKET_SESSION_KEY. Clear the POLYMARKET_CLOB_* settings if you set them (section 3).
7. Restart the app.
8. Make sure that:
   • Settings > Account shows the new signer address and Connected
   • the session key confirmed log line lists CLOB and COMBOSRFQ in scopes
   • GET /api/account shows credentials.scopes as ["trading","combos"]
   • GET /api/trading does not list combos_unavailable in combos_reasons. While the app is Safe, it lists not_armed. You can get a quote while the app is Safe
9. Revoke the old key from the owner machine (section 6). Do this only after the new key shows Connected, so that the app always has a key that works.

About the scopes in step 5:

• Use CLOB and COMBOSRFQ, not ALL (security finding P8-11). ALL also works, but it covers each venue Polymarket adds later.
• Do not use COMBOSRFQ alone. The app needs CLOB too and shows such a key as wallet_mismatch (section 7).
• The choice does not change what a leaked key can do on-chain (ADR 0012). The working-balance limit in ADR 0013 stays the same.
• The new key is valid for 180 days.

​

8.3 Exchange approvals

A combo buy spends pUSD through Polymarket’s Combos exchange (Exchange V3). A combo sell gives combo shares to that exchange. Both need the wallet’s approval of the exchange: pUSD for buys, combo positions for sells.

1. Set both approvals on polymarket.com, as the owner.

The app cannot set or read these approvals, and has no code for them. If an approval is not set, Polymarket refuses Accept. The app shows Rejected · not enough cash or allowance (venue_balance).