> ## Documentation Index
> Fetch the complete documentation index at: https://api.synthesis.trade/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Complete walkthrough from account creation to placing your first Polymarket order

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

<Steps>
  <Step title="Create a user account" />

  <Step title="Create a session or API key" />

  <Step title="Get or create a wallet" />

  <Step title="Get wallet deposit address" />

  <Step title="Place a Polymarket order" />

  <Step title="View orders and positions" />

  <Step title="Redeem and withdraw" />
</Steps>

## 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.

<CodeGroup>
  ```bash Request theme={null}
  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": "user@example.com"
        }
    }'
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "account_id": "01234567-89ab-cdef-0123-456789abcdef",
          "metadata": {
              "user_id": "your-internal-user-id",
              "email": "user@example.com"
          },
          "created_at": "2026-01-01T00:00:00"
      }
  }
  ```
</CodeGroup>

<Tip>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`.</Tip>

## Step 2: Create a session or API key

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

<CardGroup cols={2}>
  <Card title="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.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

### 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.

<CodeGroup>
  ```bash Request theme={null}
  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"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "account_id": "01234567-89ab-cdef-0123-456789abcdef",
          "session_id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789...",
          "created_at": "2026-01-01T00:00:00",
          "expires_at": "2026-01-08T00:00:00"
      }
  }
  ```
</CodeGroup>

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

```bash theme={null}
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.

<CodeGroup>
  ```bash Request theme={null}
  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"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "public_key": "pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234",
          "secret_key": "sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234",
          "name": "",
          "active": true,
          "created_at": "2026-01-01T00:00:00",
          "updated_at": "2026-01-01T00:00:00"
      }
  }
  ```
</CodeGroup>

<Warning>The `secret_key` is only shown once. Store it securely immediately after creation.</Warning>

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

```bash theme={null}
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.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallets" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": [
          {
              "wallet_id": "01234567-89ab-cdef-0123-456789abcdef",
              "name": "",
              "chains": {
                  "POL": { "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" },
                  "SOL": { "address": "BrK1t5...7mVPu" }
              },
              "position": 0,
              "autoredeem": false,
              "created_at": "2026-01-01T00:00:00"
          }
      ]
  }
  ```
</CodeGroup>

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

```bash theme={null}
curl -X POST "https://synthesis.trade/api/v1/wallet/pol" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

<Tip>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`.</Tip>

## 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:

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallet/pol" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": [
          {
              "wallet_id": "01234567-89ab-cdef-0123-456789abcdef",
              "chain_id": "POL",
              "name": "",
              "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
              "position": 0,
              "autoredeem": false,
              "created_at": "2026-01-01T00:00:00"
          }
      ]
  }
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallet/POL/{wallet_id}/deposit/EVM" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": [
          {
              "chain": "ETHEREUM",
              "address": "0x1234567890abcdef1234567890abcdef12345678",
              "tokens": [
                  {
                      "token": "USDC",
                      "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                      "min": "1",
                      "max": "100000"
                  }
              ]
          },
          {
              "chain": "ARBITRUM",
              "address": "0x1234567890abcdef1234567890abcdef12345678",
              "tokens": [ "..." ]
          }
      ]
  }
  ```
</CodeGroup>

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

### Check wallet balance

You can check the wallet balance at any time:

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/balance" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "wallet_id": "01234567-89ab-cdef-0123-456789abcdef",
          "chain_id": "POL",
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          "balance": {
              "USDC.e": "100.5"
          }
      }
  }
  ```
</CodeGroup>

## 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:

```bash theme={null}
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:

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "order_id": "0x1234567890abcdef..."
      }
  }
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/orders" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": [
          {
              "venue": "polymarket",
              "order": {
                  "order_id": "0x1234567890abcdef...",
                  "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
                  "side": "BUY",
                  "type": "MARKET",
                  "amount": "10",
                  "shares": "15.384",
                  "filled": "15.384",
                  "price": "0.65",
                  "fee": {},
                  "units": "USDC",
                  "status": "FILLED",
                  "created_at": "2026-01-01T12:00:00",
                  "updated_at": "2026-01-01T12:00:01"
              },
              "event": { "..." },
              "market": { "..." }
          }
      ]
  }
  ```
</CodeGroup>

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

```bash theme={null}
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:

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/positions" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": [
          {
              "position": {
                  "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
                  "outcome": "Yes",
                  "shares": "15.384",
                  "avg_price": "0.65",
                  "current_price": "0.72",
                  "initial_value": "10",
                  "current_value": "11.076",
                  "amount_pnl": "1.076",
                  "percent_pnl": "10.76",
                  "redeemable": false,
                  "created_at": "2026-01-01T12:00:00"
              },
              "event": { "..." },
              "market": { "..." }
          }
      ]
  }
  ```
</CodeGroup>

<Tip>For real-time order and position updates, use the [Balance WebSocket](/docs/guides/websockets/balance) which streams live balance changes including position updates and order fills.</Tip>

## 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:

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://synthesis.trade/api/v1/wallet/pol/{wallet_id}/redeem/{condition_id}" \
    -H "Authorization: Bearer YOUR_SESSION_TOKEN"
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "tx_hash": "0x9876543210fedcba..."
      }
  }
  ```
</CodeGroup>

### Withdraw funds

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

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "tx_hash": "0xfedcba9876543210..."
      }
  }
  ```
</CodeGroup>

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

## Next steps

<CardGroup cols={2}>
  <Card title="Polygon wallet endpoints" icon="arrow-right" href="/docs/api-reference">
    Explore all Polygon wallet API endpoints.
  </Card>

  <Card title="Polymarket data endpoints" icon="arrow-right" href="/docs/api-reference">
    Browse Polymarket data endpoints.
  </Card>

  <Card title="Real-time WebSockets" icon="arrow-right" href="/docs/guides/websockets/balance">
    Set up real-time data streaming.
  </Card>

  <Card title="Authentication" icon="arrow-right" href="/docs/guides/authentication/project-api-key">
    Learn more about authentication methods.
  </Card>
</CardGroup>