Step zero — from nothing to your first trade

1. Create the account. Open polymarket.com, connect a Polygon-capable EOA, and follow the venue’s current account and eligibility prompts. The repo sources do not establish a separate identity-check flow.
2. Set up credentials. If this is your first wallet, create one, store its seed phrase offline, and never share the private key. Predictefy never sees that key. You do not mint CLOB credentials manually: on the first direct SDK call, the wallet signs Polymarket’s ClobAuth message and the SDK derives existing CLOB credentials or creates them locally.
3. Fund it. A practical first test is about $10–$25 of pUSD on Polygon (137), not a venue minimum. If funds are elsewhere, use GET /v1/bridge/quote; existing USDC.e can also be wrapped through the documented funding steps.
4. Allow time. Budget 1–2 hours for a first wallet and cross-chain funding; much less if both are ready.

Polymarket applies regional eligibility rules and evaluates the submitting connection. Do not mask your location.

What you need first

• Production status: Armed for build, submit, and cancel as verified on 2026-08-15. Hosted submit remains rejected from Predictefy’s Railway US egress; the venue-direct SDK path is the working architecture and still awaits one eligible-wallet live lifecycle pass.
• Wallet and chain: A Polygon (137) EOA signs. The funds-holding maker may instead be a Polymarket Proxy or Safe for signature type 1 or 2.
• Venue account: Use a Polymarket-eligible wallet/account. The SDK derives or creates its CLOB credentials for the verified signer and account.
• Credentials: On client.accounts.polymarket, the wallet key and CLOB key/secret/passphrase stay in the caller’s process and go only to Polymarket. The legacy hosted path accepts the triple transiently but is relay-blocked.
• Funding: Polygon pUSD in the EOA, Proxy, or Safe, with approval to the applicable V2 CTF or NegRisk exchange. LI.FI can land pUSD; existing USDC.e can be wrapped through the documented funding steps.

Polymarket is server-built by default. Send plain intent parameters; Predictefy resolves the CLOB token through its own catalog, fails closed unless live GET /version returns exactly 2, and reads the token-bound tick, fee details, and NegRisk value from GET /clob-markets/{conditionId}. The CLOB NegRisk value must agree with Gamma for a new server build. Predictefy then returns the complete unsigned V2 EIP-712 order. The server never receives a private key or signs the order.

Field	Type	Required	Meaning
asset	uint256 decimal string or safe integer	this or outcome + outcomeSide	Catalog outcome id / CLOB token id
outcome	string or safe integer	with outcomeSide	Catalog market id
outcomeSide	"YES" or "NO"	with outcome	Selects the market’s catalog outcome token
isBuy	boolean	yes	BUY when true, SELL when false
price	number or numeric string in (0, 1)	yes	Rounded with the live CLOB tick rules
size	number or numeric string > 0	yes	Outcome shares; rounded down to two decimals
owner	0x… EVM address	yes	Controlling EOA signer and CLOB POLY_ADDRESS identity
funder	0x… EVM address	signature type 1 or 2	Inventory-holding Proxy/Safe maker; must differ from owner
signatureType	0, 1, or 2 (default 0)	no	EOA, Polymarket Proxy, or Polymarket Gnosis Safe verification
expiresAt	non-negative Unix seconds (default 0)	no	Wire-only expiration: 0 builds GTC; positive builds GTD
metadata	bytes32 hex (default zero bytes32)	no	Signed V2 metadata
builder	bytes32 hex (default zero bytes32)	no	Signed V2 builder code

For signature type 0, omit funder or set it equal to owner; the order has maker = signer = owner. For types 1 and 2, funder is required and must differ from owner; the signed order has maker = funder and signer = owner, and the EOA owner signs and remains the CLOB L2-auth identity.

The response keeps the established unsigned envelope (order, domain, structHash, exchange, collateral, NegRisk disclosures) and carries buildVersion: 2 plus canonical types, primaryType: "Order", and message. Pass those typed-data fields directly to eth_signTypedData_v4. The signed V2 order fields, in order, are salt, maker, signer, tokenId, makerAmount, takerAmount, side, signatureType, timestamp, metadata, and builder. timestamp is generated in Unix milliseconds. expiration remains in the relayed wire order for GTC/GTD but is not signed. V1-only taker, nonce, and feeRateBps fields are neither accepted nor relayed. Fees are operator-set and estimated from the live market fd curve, plus the live builder taker fee when a nonzero builder is used.

The domain is Polymarket CTF Exchange, version 2, on chain 137. The standard exchange is 0xE111180000d2663C0091e4f400237545B87B996B; NegRisk uses 0xe2222d279d744050d28e00520010520000310F59. Both settle pUSD (0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB) with six decimals. The echoed buildResult path also requires V2; a V1 echo is rejected as a new-order artifact.

Client-side submit: the working Polymarket route

Polymarket geo-evaluates the network connection that submits the CLOB order. The production execution ledger shows that every hosted submit ever attempted was venue-rejected because the venue saw Predictefy’s Railway US relay IP, not the caller. The SDK therefore uses Predictefy only to build the complete unsigned order. It reconstructs and verifies that server artifact, signs it with the caller’s wallet, and sends the signed order directly from the caller’s connection to https://clob.polymarket.com.

import { Predictefy, PREDICTEFY_EXEC_BASE_URL } from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
  execBaseUrl: PREDICTEFY_EXEC_BASE_URL,
  venueCredentials: { polymarket: { address: account.address } },
});

const placed = await client.accounts.polymarket.createOrder(
  {
    idempotencyKey: 'your-stable-build-key',
    asset: '987654321',
    isBuy: true,
    price: 0.4,
    size: 10,
    owner: account.address,
    signatureType: 0,
  },
  account,
);

const accountAuth = { address: account.address, signer: account };
const status = await client.accounts.polymarket.fetchOrder(placed.orderId, accountAuth);
const canceled = await client.accounts.polymarket.cancelOrder(placed.orderId, accountAuth);

Before signing, the SDK binds the returned token, side, rounded maker/taker amounts, identities, signature type, metadata, builder, and expiration to the original caller intent. Only an explicit allowlist of plain order fields crosses the hosted build boundary; an unknown field is rejected by name while its value remains redacted. Both token-selection modes are independently bound. With asset, the signed CLOB token id must equal the caller’s value and the SDK performs no Gamma lookup. With outcome + outcomeSide, the SDK sends the caller-pinned catalog id — never a builder-selected condition or market id — to https://gamma-api.polymarket.com/markets/{id}, requires exactly one case-insensitive Yes and one No outcome, and checks the signed token against the requested side by array position. Gamma’s authoritative negRisk boolean also pins the EIP-712 domain to the fixed standard or NegRisk exchange. The Gamma request carries no headers, refuses redirects, and its immutable mapping is cached per SDK client. A venue-read failure, malformed mapping, foreign-market token, opposite-side token, or exchange mismatch is a typed refusal before signTypedData.

On the first call, the SDK asks the same wallet to sign Polymarket’s ClobAuth EIP-712 message, tries to derive the wallet’s existing CLOB API credentials, and creates them if no credential exists for nonce 0. It caches the triple by explicit account and verified signer address. Every cache lookup re-verifies the signer, and authenticated status, cancel, and open-orders calls require an explicit account context. You may instead provide an existing triple under venueCredentials.polymarket for that address.

The private key remains inside the caller’s signer. The order signature, ClobAuth signature, CLOB API credentials, and HMAC headers never transit a Predictefy host. The optional hosted fetch override is never reused for venue traffic; a separate credential-trusted venueFetch override is available when required. Credentialed requests are pinned to clob.polymarket.com, every redirect is refused, and transport/HTTP failures return only typed generic errors without upstream text. This path exposes the caller’s real connection to the venue; callers must still satisfy Polymarket’s own account and jurisdiction rules and must not mask their location.

The endpoint shapes are checked against current official Polymarket documentation, and fixture tests byte-pin the L1 typed data, L2 HMAC headers, and order body against the existing execution implementation. No live venue call is made by the test suite. One eligible-wallet derive/create → submit → status → cancel pass is still required before calling this route production-live.