Getting started

This guide walks you through the complete flow of integrating Synthesis into your application. By the end, you’ll have created a user account, set up authentication, created a wallet, and placed your first Polymarket order.

What you’ll learn

Create a user account

Create a session or API key

Get or create a wallet

Get wallet deposit address

Place a Polymarket order

View orders and positions

Redeem and withdraw

Prerequisites

Before you begin, make sure you have:

A Synthesis project with your X-PROJECT-API-KEY
Basic familiarity with REST APIs and HTTP requests

Step 1: Create a user account

The first step is to create a user account for your end user. This is done from your backend using your project secret API key. Each account represents a unique user in your application and can have multiple wallets, sessions, and API keys. The metadata field is optional and can store any JSON data you want to associate with the account, such as your internal user ID, email, or other identifiers.

curl -X POST "https://synthesis.trade/api/v1/project/account" \
  -H "Content-Type: application/json" \
  -H "X-PROJECT-API-KEY: YOUR_PROJECT_API_KEY" \
  -d '{
      "metadata": {
          "user_id": "your-internal-user-id",
          "email": "[email protected]"
      }
  }'

Save the account_id from the response. You’ll need it to create sessions and API keys for this user. Alternatively, you can retrieve existing accounts by calling GET /api/v1/project/accounts.

Step 2: Create a session or API key

Now you need to authenticate the user. There are two approaches depending on your use case:

Option A: Session token

Best for frontend applications. Create a session and store the token in the user’s browser. Sessions expire after a period of inactivity but can be refreshed.

Option B: Account API key

Best for backend services. Create a long-lived API key that your server can use to make requests on behalf of the user. API keys don’t expire unless revoked.

Option A: Create a session

Create a session for the account. The session token should be stored securely in the user’s browser (e.g., in an HTTP-only cookie or secure storage) and sent with each request.

curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/session" \
  -H "Content-Type: application/json" \
  -H "X-PROJECT-API-KEY: YOUR_PROJECT_API_KEY"

Use the session token in the Authorization header for all subsequent account requests:

curl -X GET "https://synthesis.trade/api/v1/account/session" \
  -H "Authorization: Bearer aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789..."

Option B: Create an account API key

Create a long-lived API key for the account. Store this securely on your backend server. Never expose account API keys to the frontend.

curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/api-key" \
  -H "Content-Type: application/json" \
  -H "X-PROJECT-API-KEY: YOUR_PROJECT_API_KEY"

The secret_key is only shown once. Store it securely immediately after creation.

Use the secret key in the X-API-KEY header for all subsequent account requests:

curl -X GET "https://synthesis.trade/api/v1/account/session" \
  -H "X-API-KEY: sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234"

Step 3: Get or create a wallet

Each account can have multiple wallets for trading. The easiest way to get started is to call the GET /api/v1/wallets endpoint, which will automatically create a Polygon wallet if one doesn’t exist.

curl -X GET "https://synthesis.trade/api/v1/wallets" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Alternatively, you can explicitly create a wallet using the create wallet endpoint:

curl -X POST "https://synthesis.trade/api/v1/wallet/pol" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Save the wallet_id from the response. You’ll use it for deposits, orders, and other wallet operations. You can always retrieve your wallets later by calling GET /api/v1/wallet.

Step 4: Get wallet deposit address

Before placing orders, the wallet needs USDC. There are two ways to get deposit addresses.

Option A: Native Polygon deposit

The wallet’s Polygon address can receive USDC directly on the Polygon network:

curl -X GET "https://synthesis.trade/api/v1/wallet/pol" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Display the address to your user so they can deposit USDC (on Polygon) to fund their trading wallet.

Option B: Cross-chain deposit

Users can also deposit from other chains (Ethereum, Base, Arbitrum, Solana, etc.) using the cross-chain deposit endpoint. This generates a unique deposit address that automatically bridges funds to the Polygon wallet:

curl -X GET "https://synthesis.trade/api/v1/wallet/POL/{wallet_id}/deposit/EVM" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Supported chain parameter values: EVM (Ethereum, Arbitrum, Base, Optimism, Binance), SOL, TRON.

Check wallet balance

You can check the wallet balance at any time:

curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/balance" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Step 5: Place a Polymarket order

Now you’re ready to place your first order. You’ll need the token_id of the market outcome you want to trade. You can get this from the market endpoints. First, find a market and get its token IDs:

curl -X GET "https://synthesis.trade/api/v1/markets/search/bitcoin?venue=polymarket"

Then place a market order. This example buys $10 worth of YES shares at market price:

curl -X POST "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
      "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
      "side": "BUY",
      "type": "MARKET",
      "amount": "10",
      "units": "USDC"
  }'

Order types

Type	Description
`MARKET`	Execute immediately at best available price
`LIMIT`	Execute only at specified price or better
`STOPLOSS`	Trigger a market sell when price drops to threshold

Order parameters

Parameter	Description
`token_id`	The Polymarket token ID for the outcome you want to trade
`side`	`BUY` or `SELL`
`type`	`MARKET`, `LIMIT`, or `STOPLOSS`
`amount`	Order amount as a string
`units`	`USDC` (dollar amount) or `SHARES` (number of shares)
`price`	Required for LIMIT and STOPLOSS orders (0.001 to 0.999)

Step 6: View orders and positions

After placing orders, you can track their status and view your positions. Orders can be in various states: OPEN (active on the orderbook), PARTIAL (partially filled), FILLED (fully filled), CANCELED, or FAILED.

Get orders

Retrieve all orders for a wallet, including historical and active orders:

curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/orders" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

To get only active orders (orders currently on the orderbook):

curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/orders/active" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Get positions

View all positions (shares) held by the wallet. Positions represent ownership of outcome tokens in prediction markets:

curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/positions" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

For real-time order and position updates, use the Balance WebSocket which streams live balance changes including position updates and order fills.

Step 7: Redeem and withdraw

When a market resolves, you can redeem your winning positions for USDC.e. After redemption, you can withdraw funds to any external wallet.

Redeem a position

After a market resolves, redeem your winning shares for USDC.e. You need the condition_id from your position:

curl -X POST "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/redeem/{condition_id}" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Withdraw funds

Withdraw USDC.e from your Synthesis wallet to any external Polygon address:

curl -X POST "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/withdraw" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
      "token": "USDC.e",
      "amount": "50",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

Withdrawals are processed on the Polygon network. Make sure the destination address is a valid Polygon address that can receive USDC.e tokens.

Next steps

Polygon wallet endpoints

Explore all Polygon wallet API endpoints.

Polymarket data endpoints

Browse Polymarket data endpoints.

Real-time WebSockets

Set up real-time data streaming.

Authentication

Learn more about authentication methods.

Overview

Authentication

Real-time Data

Getting started

What you’ll learn

Prerequisites

Step 1: Create a user account

Step 2: Create a session or API key

Option A: Session token

Option B: Account API key

Option A: Create a session

Option B: Create an account API key

Step 3: Get or create a wallet

Step 4: Get wallet deposit address

Option A: Native Polygon deposit

Option B: Cross-chain deposit

Check wallet balance

Step 5: Place a Polymarket order

Order types

Order parameters

Step 6: View orders and positions

Get orders

Get positions

Step 7: Redeem and withdraw

Redeem a position

Withdraw funds

Next steps

Polygon wallet endpoints

Polymarket data endpoints

Real-time WebSockets

Authentication

Overview

Getting Started

Authentication

Real-time Data

​What you’ll learn

​Prerequisites

​Step 1: Create a user account

​Step 2: Create a session or API key

Option A: Session token

Option B: Account API key

​Option A: Create a session

​Option B: Create an account API key

​Step 3: Get or create a wallet

​Step 4: Get wallet deposit address

​Option A: Native Polygon deposit

​Option B: Cross-chain deposit

​Check wallet balance

​Step 5: Place a Polymarket order

​Order types

​Order parameters

​Step 6: View orders and positions

​Get orders

​Get positions

​Step 7: Redeem and withdraw

​Redeem a position

​Withdraw funds

​Next steps

Polygon wallet endpoints

Polymarket data endpoints

Real-time WebSockets

Authentication

What you’ll learn

Prerequisites

Step 1: Create a user account

Step 2: Create a session or API key

Option A: Create a session

Option B: Create an account API key

Step 3: Get or create a wallet

Step 4: Get wallet deposit address

Option A: Native Polygon deposit

Option B: Cross-chain deposit

Check wallet balance

Step 5: Place a Polymarket order

Order types

Order parameters

Step 6: View orders and positions

Get orders

Get positions

Step 7: Redeem and withdraw

Redeem a position

Withdraw funds

Next steps