API Integration
API Specification
The full V3 gateway REST surface, and where to find exact request and response schemas.
The V3 gateway is a typed REST API served from https://pro-gateway.pearprotocol.io. The source of truth for every request and response shape is the TypeScript SDK and its types package:
@pear-protocol/core-sdk, the typed REST client (sdk.auth,sdk.core).@pear-protocol/types, Zod schemas and DTOs for every request, response, and entity.
Prefer the SDK over raw HTTP: it wraps authentication, x-trade-account-id scoping, and returns fully typed results.
Endpoint groups
| Group | Routes | SDK |
|---|---|---|
| Auth | /auth/nonce, /auth/login, /auth/session/*, /auth/api-key/me | sdk.auth |
| Trade accounts | /trade-accounts, /trade-accounts/:id, .../credentials | sdk.core.accounts |
| API keys | /api-keys, /api-keys/:id | sdk.core.apiKeys |
| Trade | /trade/open, /trade/:id/adjust, /trade/:id/close, /trade/:id/reverse, /trade/close-all, PUT /leverage | sdk.core.trade |
| Triggers | /triggers/open, /triggers/close, /triggers, /triggers/:id/cancel | sdk.core.triggers |
| Schedules (TWAP) | /schedules, /schedules/:id/cancel | sdk.core.schedules |
| Ladders | /ladders, /ladders/:id, /ladders/:id/cancel | sdk.core.ladders |
| Rebalance | /rebalance/manual/:id, /rebalance/auto, /rebalance/:id/events | sdk.core.rebalance |
| Positions | /positions, /positions/lite | sdk.core.positions |
| Executions | /executions, /executions/:id | sdk.core.executions |
| Fills | /fills, /fills/:positionId | sdk.core.fills |
| Portfolio | /portfolio, /portfolio/analytics | sdk.core.portfolio |
| Markets | /markets, /markets/baskets | sdk.core.markets |
| Instruments and prices | /instruments, /prices, /funding | sdk.core.instruments / prices / funding |
| Saved baskets | /saved-baskets, /saved-baskets/:id | sdk.core.savedBaskets |
| Notifications | /notifications, /notifications/read | sdk.core.notifications |
| Statistics and TCA | /statistics/*, /tca/* | sdk.core.statistics / tca |
| Users | /users/profile, /users/preferences | sdk.core.users |
Real-time updates (prices, funding, fills, positions, triggers) come over the WebSocket, not REST.
Interactive reference
A full interactive OpenAPI reference (every field, enum, and example) is generated from the gateway's OpenAPI spec. Until it is mounted here, use the SDK types (@pear-protocol/types) as the authoritative schema.