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

# Integration Patterns

> Two ways to integrate Polymarket trading: one chain-abstracted getAction call, or the direct three-step flow.

Swaps supports two integration patterns for placing prediction market orders.
The **chain-abstracted** pattern is the core value proposition: users transact
on Polymarket with **any token on any chain, directly from their existing
wallet** — instead of needing a Polymarket trading account and pUSD. The
**direct** pattern trades that simplicity for control over funding and order
timing.

Both settle on the same rails: the user's deposit (proxy) wallet on Polygon
and the Polymarket CLOB.

|                         | Chain abstracted                           | Direct                                                                                                    |
| ----------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Calls to place an order | 1 (`getAction`)                            | 3 (`createOrFetchPolymarketUser` → fund → `placeOrder`)                                                   |
| Source of funds         | Any token on any chain, per order          | Pre-funded deposit wallet (collateral on Polygon)                                                         |
| EIP-712 signature       | Not required to place                      | Required on every trading call — see the [signing guide](/prediction-market-reference/polymarket-signing) |
| Order latency           | Swap + order (cross-chain settlement time) | Order only — immediate against the CLOB                                                                   |
| Best for                | "Let users bet with whatever they hold"    | Trading UIs with balances, repeat orders, tighter control                                                 |

## Pattern 1 — Chain abstracted (one call)

One `getAction` request with `actionType=polymarket` swaps any token on any
chain into collateral and places the order when funds arrive. The only setup
is a one-time `createOrFetchPolymarketUser` call your app makes behind the
scenes to provision the user's deposit wallet. Full parameter reference:
[Place Order (Chain Abstracted)](/prediction-market-reference/place-order-chain-abstracted).

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App as Your App
    participant Swaps as Swaps API
    participant CLOB as Polymarket CLOB

    Note over App,Swaps: one-time setup per user
    App->>Swaps: POST /createOrFetchPolymarketUser (evmEoa)
    Swaps-->>App: userId + deposit wallet
    Note over App,Swaps: per order
    App->>Swaps: GET /getAction (actionType=polymarket, userId)
    Swaps-->>App: transaction + txId
    User->>User: sign & broadcast transaction
    Note over Swaps: swap settles, collateral lands in deposit wallet
    Swaps->>CLOB: place order
    App->>Swaps: GET /workflows/getStatus?txId=...
    Swaps-->>App: workflow status + order result
```

## Pattern 2 — Direct (three steps)

The direct flow separates account setup, funding, and ordering. Once the
deposit wallet is funded, orders execute immediately against the CLOB with no
swap in the critical path.

### Step 1 — Deploy the deposit wallet

Call [`POST /createOrFetchPolymarketUser`](/prediction-market-reference/create-or-fetch-user)
with the user's `evmEoa`. It returns the `userId` and a deposit (proxy) wallet
keyed to that EOA, deploying one if it doesn't exist yet.

Check `proxyWalletStatus` before trading:

| Status                                | Meaning                                                                       |
| ------------------------------------- | ----------------------------------------------------------------------------- |
| `ready`                               | Wallet is deployed and tradeable.                                             |
| `deploying` / `permissioning`         | Setup in progress — poll until `ready`.                                       |
| `failed-deploy` / `failed-permission` | Setup failed — retry the call.                                                |
| `temporary-frozen`                    | Wallet is frozen — call the endpoint again with `unfreeze: true` in the body. |
| `not-created`                         | No wallet yet — the call will create one.                                     |

### Step 2 — Fund the deposit wallet

Fund the wallet with Polymarket collateral — **pUSD on Polygon**
(`0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`, chain `137`). From any other
token or chain, use a standard [`getAction` swap](/swap-api-reference/get-action)
with the deposit wallet as the `recipient`:

```bash theme={null}
curl "https://api-v2.swaps.xyz/api/getAction?\
actionType=swap-action&\
sender=0xB9519a08267d7B259eCA6DbD8F7286B1f176A41f&\
srcChainId=8453&\
srcToken=0x0000000000000000000000000000000000000000&\
dstChainId=137&\
dstToken=0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB&\
amount=10000000000000000&\
swapDirection=exact-amount-in&\
slippage=100&\
recipient=<DEPOSIT_WALLET_ADDRESS>" \
  -H "x-api-key: $API_KEY"
```

### Step 3 — Place the order

Call [`POST /placeOrder`](/prediction-market-reference/place-order) with the
order details and an EIP-712 `signatureByEvmEoa` produced by the user's EOA —
Swaps verifies the signature and relays the order to the Polymarket CLOB. See
the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing)
for the typed-data schema and a working example.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App as Your App
    participant Swaps as Swaps API
    participant CLOB as Polymarket CLOB

    App->>Swaps: POST /createOrFetchPolymarketUser (evmEoa)
    Swaps-->>App: userId + deposit wallet (proxyWalletStatus)
    App->>Swaps: GET /getAction (swap to pUSD on Polygon, recipient = deposit wallet)
    User->>User: sign & broadcast funding transaction
    Note over Swaps: collateral lands in deposit wallet
    User->>User: sign PlaceOrder typed data (EIP-712)
    App->>Swaps: POST /placeOrder (signatureByEvmEoa)
    Swaps->>CLOB: relay order
    Swaps-->>App: txId + orderResponse
```

## After the order

Both patterns converge on the same lifecycle: track execution with
[`GET /workflows/getStatus`](/prediction-market-reference/get-workflow-status),
then manage positions with sell, redeem, merge, and withdraw. See the
[Transaction Lifecycle](/prediction-market-reference/transaction-lifecycle)
for the end-to-end walkthrough.