Syncing Venue Activity

A trade account is an exchange account, and you can trade it without Pear. When you do, Pear's ledger and the venue's disagree until someone tells Pear what happened. The POST /sync/fills/* and POST /sync/funding/* endpoints are how you tell it.

The sync is client-driven. Pear does not poll the exchange for you: per-IP rate limits at the venues make that impossible at scale. Your client reads the venue with your own credentials, works out what Pear is missing, and posts it.

This is what produces the EXTERNAL and PARTIAL values of a position's origin, and the isExternal flag on a fill. See Synthetic Position and Fills.

Most integrations never call these endpoints. If you write TypeScript, use the syncer in @pear-protocol/exchanges-sdk and skip to What gets rejected. The raw endpoints are documented for callers who cannot.

Use the SDK syncer

createSyncer(connection) returns an AccountSyncer that runs a whole cycle for you: it reads Pear's state, reads the venue, diffs them, and posts the result across the sync endpoints.

import PearSDK from '@pear-protocol/core-sdk';
import { ExchangesSDK } from '@pear-protocol/exchanges-sdk';

const exchanges = new ExchangesSDK({ sdk });

const connection = await exchanges.connect(tradeAccountId);
const syncer = exchanges.createSyncer(connection);

const fills = await syncer.synchronizeFills();
const funding = await syncer.synchronizeFunding();

Both methods return an outcome rather than throwing on the normal failure paths:

'deferred' and 'aborted' are both normal. Neither is an error to alert on unless it repeats.

Anything else still throws: a rejected post, a validation failure, or a 409 that is not a SYNC_CREATE_* deferral. Only the exchange read is guarded.

The two cycles are independent. Funding rows are immutable and upsert idempotently, so run synchronizeFunding() on its own cadence rather than pairing it with every fill cycle.

connect() opens a connection from a trade account. The rest of that SDK is in Venue Accounts.

The endpoints

Ten endpoints, all POST, all scoped to one trade account through x-trade-account-id. All ten are writes, so a read API key gets 403.

The eight write endpoints answer 200 with an empty object, {}. There is no id, no count, and no per-row result. Read the outcome back from GET /positions and GET /fills.

The venue always comes from the trade account. connector is required on the fill and payment objects, but the value stored is the trade account's own.

One fill cycle

Order matters. Reconcile and confirm first, create last. Both settle fills Pear already owns, and create then applies what is left and checks the result against the venue's position snapshot. Settling first is what keeps a fill Pear placed from being imported a second time as a foreign one.

You also need three read endpoints to build the payload:

The watermark

POST /sync/fills/since answers the only question you cannot answer yourself: how far back to read the venue.

curl -X POST "https://pro-gateway.pearprotocol.io/sync/fills/since" \
  -H "x-api-key: $PEAR_API_KEY" \
  -H "x-trade-account-id: $TRADE_ACCOUNT_ID" \
  -H "content-type: application/json" \
  -d '{ "overlapMs": 60000 }'

{
  "sinceMs": 1767225540000,
  "neverSynced": false,
  "confirmedExchangeFillIds": ["42917301", "42917305"]
}

overlapMs is required, and must be a positive integer. The gateway subtracts it from the reference timestamp and floors the result at 0, so the window deliberately reaches back behind what has already been imported. That overlap is what recovers a fill the venue published late.

Because the window overlaps, you will re-read fills you already imported. Drop every fill whose id is in confirmedExchangeFillIds before you build the payload. Compare ids case-insensitively, after trimming. That list is the only deduplication the watermark gives you.

sinceMs === 0 alone is ambiguous: a clamped watermark produces it too. Branch on neverSynced, not on the zero.

How it advances

Pear keeps one checkpoint per phase. Each write endpoint moves only its own:

POST /sync/fills/since then takes the earliest of the reconcile, confirm, and create checkpoints, and pulls the result back further to the oldest provisional fill still outstanding. So one lagging phase holds the window open for all three, and an unsettled provisional fill keeps its own window open until it settles.

With no checkpoint at all, the window anchors on the oldest open position or the oldest provisional fill, whichever is earlier. With none of those either, it is 0 and neverSynced is true.

POST /sync/funding/since reads the funding checkpoint alone.

Three rules follow:

• A rejected call advances nothing. The next cycle sees the same sinceMs and retries the same window. This is what makes a 'deferred' outcome safe to ignore.
• Set meta.externalMaxTs to the timestamp of the newest fill you processed, or null when you fetched none.
• meta.externalMaxTs must not be more than 300000 ms ahead of the gateway's clock. Beyond that it is a 400. The margin absorbs clock drift; a seconds-instead-of-milliseconds mistake overshoots it by orders of magnitude, which is the point.

POST /sync/funding/since is the same call with a smaller answer. Funding has no positions or provisional fills to anchor on, so the watermark is the only reference:

{ "sinceMs": 1767225540000 }

The fill lifecycle

A fill has three statuses. Fills covers what each one means for reading; this is what moves between them.

Two consequences:

• A fill written by create is never PROVISIONAL. Only Pear's own order placement writes a provisional row, because only Pear knows a client order id before the venue prints against it. Everything you import is confirmed on arrival.
• A reconciled fill's id disappears. RECONCILED rows are never returned by any read endpoint, and the replacements carry new ids. Match on exchangeFillId.

Confirm

Keyed by position id. Each value is a non-empty array of fills, and every fill in it must repeat that same positionId.

curl -X POST "https://pro-gateway.pearprotocol.io/sync/fills/confirm" \
  -H "x-api-key: $PEAR_API_KEY" \
  -H "x-trade-account-id: $TRADE_ACCOUNT_ID" \
  -H "content-type: application/json" \
  -d @confirm.json

{
  "9c1b2d3e-4f56-4789-a0b1-c2d3e4f56789": [
    {
      "type": "confirm",
      "exchangeFillId": "42917338",
      "cloid": "0x9f2c4a7e10b3486d",
      "positionId": "9c1b2d3e-4f56-4789-a0b1-c2d3e4f56789",
      "connector": "hyperliquid",
      "symbol": "0",
      "quantity": "0.0052",
      "timestamp": 1767225601240,
      "tradeFee": "0.22",
      "builderFee": "0.05"
    }
  ]
}

The object must hold at least one key.

Reconcile

Keyed by client order id. Each value is an array of two or more sibling fills that all carry that same cloid. Use it when one order Pear placed came back from the venue as several prints.

{
  "0x9f2c4a7e10b3486d": [
    {
      "exchangeFillId": "42917338",
      "cloid": "0x9f2c4a7e10b3486d",
      "connector": "hyperliquid",
      "symbol": "0",
      "price": "96150.5",
      "quantity": "0.0030",
      "side": "BUY",
      "reduceOnly": false,
      "timestamp": 1767225601240,
      "tradeFee": "0.13",
      "builderFee": "0.03",
      "liquidation": null
    },
    {
      "exchangeFillId": "42917341",
      "cloid": "0x9f2c4a7e10b3486d",
      "connector": "hyperliquid",
      "symbol": "0",
      "price": "96152.0",
      "quantity": "0.0022",
      "side": "BUY",
      "reduceOnly": false,
      "timestamp": 1767225601310,
      "tradeFee": "0.09",
      "builderFee": "0.02",
      "liquidation": null
    }
  ]
}

Every sibling must agree with the provisional fill it replaces, and with the others:

liquidation is required, and nullable. Send null for an ordinary fill, or { "mark": "96150.5" } when the venue liquidated the position at that mark.

Applying external fills

POST /sync/fills/create is the endpoint that actually imports activity. It takes three things: the baskets of fills to apply, the venue's current position snapshot, and the cycle metadata.

{
  "applicables": [
    {
      "positionKey": "1e0f4d2c9b8a7f6e5d4c3b2a190807060504030201f0e0d0c0b0a09080706050",
      "exposure": { "0": "+0.0052", "1": "-0.1620" },
      "origin": "EXTERNAL",
      "status": "OPEN",
      "fills": [
        {
          "exchangeFillId": "42917402",
          "cloid": null,
          "connector": "hyperliquid",
          "symbol": "0",
          "side": "BUY",
          "quantity": "0.0052",
          "price": "96150.5",
          "usd": "500.00",
          "timestamp": 1767225601240,
          "reduceOnly": false,
          "synthetic": false,
          "isExternal": true,
          "tradeFee": "0.22",
          "builderFee": "0"
        },
        {
          "exchangeFillId": "42917403",
          "cloid": null,
          "connector": "hyperliquid",
          "symbol": "1",
          "side": "SELL",
          "quantity": "0.1620",
          "price": "3086.2",
          "usd": "500.00",
          "timestamp": 1767225601310,
          "reduceOnly": false,
          "synthetic": false,
          "isExternal": true,
          "tradeFee": "0.21",
          "builderFee": "0"
        }
      ],
      "metadata": {
        "initialExposureUSD": { "0": "+500.00", "1": "-500.00" }
      }
    }
  ],
  "exchangePositions": [
    { "symbol": "0", "size": "0.0052", "side": "BUY", "entryPrice": "96150.5", "markPrice": "96420.0" },
    { "symbol": "1", "size": "0.1620", "side": "SELL", "entryPrice": "3086.2", "markPrice": "3081.4" }
  ],
  "meta": {
    "externalMaxTs": 1767225601310,
    "newestFillTs": 1767225601310
  }
}

applicables and exchangePositions may both be empty arrays. meta is required.

The applicable

One applicable is one target position. Pear finds the position by positionKey and merges into it, or creates it when there is none.

Your client is the authority on exposure, origin, and status. The gateway writes them without recomputing, then checks the total against exchangePositions. A flip is two applicables sharing one positionKey, {"status": "CLOSED"} first and {"status": "OPEN"} second, in that order.

positionKey is the lowercase hex SHA-256 of this exact JSON, with the two keys in this order and the symbols sorted ascending by string comparison:

{"tradeAccountId":"<trade account id, lowercased>","symbols":["0","1"]}

No connector, and no side. Two positions on the same asset set therefore share a key, which is what lets Pear find the one correct target.

The applicable fill

Fees are never verified against the venue, and they flow straight into portfolio, TCA, and leaderboard numbers. Send what the venue reported.

The snapshot is the referee

exchangePositions is the venue's own open-position list, normalized to base units. It is not advisory. After applying your fills, Pear folds every non-closed position on the account into a per-instrument total and compares it to this snapshot. Any mismatch on any instrument rolls the entire cycle back and answers 400, with a message naming the instrument and both numbers.

So the snapshot must be read from the venue in the same cycle as the fills, and the fills you send must explain the difference between what Pear holds and what the snapshot says. Where they cannot, send a synthetic fill to bridge the gap.

Cycle metadata

Keep newestFillTs and externalMaxTs separate. If you ever advance externalMaxTs past the real newest fill, the freshness gate would measure the adjusted value and let through a cycle whose fills have not settled.

Funding

POST /sync/funding/create takes the funding events since the funding watermark. Rows upsert idempotently on trade account, connector, instrument, and timestamp, so re-posting the overlap window is free.

{
  "payments": [
    {
      "connector": "hyperliquid",
      "instrumentId": "0",
      "fundingRate": "0.0000125",
      "notional": "-0.62",
      "fundingPerUnit": "-119.23",
      "timestamp": 1767225600000
    }
  ],
  "meta": { "externalMaxTs": 1767225600000 }
}

payments may be an empty array. That writes no rows, and still advances the funding watermark when meta.externalMaxTs is set.

Until an account has funding history, GET /portfolio/analytics reports config.fundingSynced: false and its funding figures are unknown, not zero. See Trade History.

The bulk variants

Four endpoints take the same payload as a gzipped file upload instead of a JSON body: /sync/fills/reconcile/bulk, /sync/fills/confirm/bulk, /sync/fills/create/bulk, and /sync/funding/create/bulk. The gateway forwards the compressed bytes to a worker, which decompresses and validates them off the shared API.

gzip -c payload.json > payload.json.gz

curl -X POST "https://pro-gateway.pearprotocol.io/sync/fills/create/bulk" \
  -H "x-api-key: $PEAR_API_KEY" \
  -H "x-trade-account-id: $TRADE_ACCOUNT_ID" \
  -F "file=@payload.json.gz"

Do not set content-type yourself. The multipart boundary has to come from your HTTP client.

A missing or empty file field is a 400 with the framework error shape and a message naming the field, such as Missing gzipped create payload in the "file" field.

The SDK switches automatically: it measures the JSON body and uses the bulk path above 50 KB. Below that, the plain endpoint is cheaper. Neither since endpoint has a bulk variant, because each takes a single field.

What gets rejected

The four 409s are the ones to build for. They apply to /sync/fills/create and its bulk twin only; reconcile, confirm, and both funding endpoints have no such gate. None of the four is a rejection of your payload. Nothing was written, the watermark did not move, and the same request will succeed once the account settles. Back off and retry.

Read minFillAgeSeconds from details rather than hard-coding a wait. It is configuration, not contract.

SYNC_CREATE_FILLS_TOO_RECENT reaches the plain endpoint before anything runs. On the bulk endpoint the freshness check happens in the worker, after decompression, because the timestamps are inside the gzip. The other three behave identically on both paths.

Everything else:

See Error Handling for both body shapes.

Two rejections worth calling out, because they look like bugs and are not:

• A confirm or reconcile whose exchangeFillId Pear already has is a 400, not a no-op. The endpoints are not idempotent on retry. Refresh the provisional list and rebuild the payload rather than replaying the old one.
• A verify mismatch rolls back fills that were individually valid. The apply and the check share one transaction. A partial import is never left behind.