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

# Connection

> One connection carries any number of feeds, each one channel of one instrument.

- Sign an empty `GET /v1` as the [Authentication guide](https://docs.services.payward.com/tabs/developer-documentation/get-started/authentication) describes.
- Answer the server's pings, sent every 20 seconds.
- Close codes: `1011` a feed failed, `1001` restart or missed pings, `1003` binary frame. Reconnect and resubscribe; nothing is replayed.

```text WSS
wss://ws.sandbox.services.payward.com/v1
```


## OpenAPI

````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json get /v1
openapi: 3.1.0
info:
  title: PWS Public API
  version: '1'
  description: >-
    Integrate with Payward Services to onboard users, manage accounts and funds,
    trade assets, and receive event notifications.
  contact:
    name: Payward Services
servers:
  - url: https://api.sandbox.services.payward.com
security: []
tags:
  - name: Assets
    description: List the assets PWS is willing to swap.
    x-displayName: Assets
  - name: Conversions
    description: >-
      Rule-driven and on-demand fiat ↔ crypto value movement, including
      conversion rules and deposits.
    x-displayName: Conversions
  - name: Auto Earn
    description: >-
      Manage Auto Earn preferences and retrieve allocation and reward
      information.
    x-displayName: Auto Earn
  - name: Bonded Earn
    description: >-
      Allocate funds to and deallocate funds from bonded earn strategies, review
      allocations, and track request status.
    x-displayName: Bonded Earn
  - name: Funding
    description: >-
      Discover deposit and withdrawal options, manage deposit addresses, and
      move funds between accounts.
    x-displayName: Funding
  - name: Derivatives transfers
    description: >-
      Move funds between an account's spot balance and the same owner's futures
      balance.
    x-displayName: Derivatives transfers
  - name: Portfolio
    description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.'
    x-displayName: Portfolio
  - name: Ramp
    description: >-
      Support Ramp flows with discovery, quotes, limits, and hosted checkout
      experiences.
    x-displayName: Ramp
  - name: Reports
    description: Settlement and reconciliation reports for the partner.
    x-displayName: Reports
  - name: Market data stream
    description: Live market data for derivatives instruments.
    x-displayName: Market data stream
  - name: Derivatives instruments
    description: Discover instruments available for trading by asset type.
    x-displayName: Derivatives instruments
  - name: Derivatives tickers
    x-group: Derivatives market data
    description: Read market-data snapshots for supported trading instruments.
    x-displayName: Derivatives tickers
  - name: Derivatives order books
    x-group: Derivatives market data
    description: Read level-two market depth for supported trading instruments.
    x-displayName: Derivatives order books
  - name: Derivatives OHLC
    x-group: Derivatives market data
    description: Read historical candlestick market data for supported trading instruments.
    x-displayName: Derivatives OHLC
  - name: Derivatives orders
    description: Submit and inspect orders by asset type.
    x-displayName: Derivatives orders
  - name: Derivatives trades
    description: Inspect executions by asset type.
    x-displayName: Derivatives trades
  - name: Derivatives leverage
    description: Read and update per-instrument leverage preferences for trading accounts.
    x-displayName: Derivatives leverage
  - name: Swaps
    description: Account-funded quotes that lock a price until they expire or are executed.
    x-displayName: Swaps
  - name: Onchain quotes
    description: Wallet-funded quotes that return the data needed to settle onchain.
    x-displayName: Onchain quotes
  - name: Price trigger swaps
    description: Swaps that wait for a target price before submitting a trade.
    x-displayName: Price trigger swaps
  - name: Travel Rule verifications
    description: Travel Rule address ownership verification flows.
    x-displayName: Travel Rule verifications
  - name: Users
    description: >-
      User onboarding and status flows that the partner manages.


      - **Create User** provisions an account-owned user from an external
      reference and optional email.

      - **Get User** retrieves the user's profile, verification status, and
      required actions.


      Use the returned user `id` for calls that require the user's identifier.
    x-displayName: Users
  - name: Verifications
    description: Identity verification (KYC) submission and status for end users.
    x-displayName: Verifications
  - name: Webhooks
    description: >-
      Register HTTPS destinations to receive event deliveries, rotate signing
      secrets, and inspect, update, or delete existing subscriptions. Each
      subscription is owned by the authenticated partner; deliveries are signed
      with HMAC-SHA256 and retried on transient failures.


      In webhook payloads, `account_id` and `user_id` are in groups of four
      characters, with a space between the groups. For example, `WCQY T95Y CUL2
      A7NX`. The REST APIs send the same identifier without spaces, for example
      `WCQYT95YCUL2A7NX`. Remove the spaces before you compare a webhook
      identifier with a REST identifier.


      Amounts in webhook payloads are decimal strings, in the ledger precision
      of the asset. Compare amounts as decimal numbers, not as strings.
    x-displayName: Webhooks
paths:
  /v1:
    servers:
      - url: wss://ws.sandbox.services.payward.com
        description: Sandbox
    get:
      tags:
        - Market data stream
      summary: Connection
      description: >-
        One connection carries any number of feeds, each one channel of one
        instrument.


        - Sign an empty `GET /v1` as the [Authentication
        guide](https://docs.services.payward.com/tabs/developer-documentation/get-started/authentication)
        describes.

        - Answer the server's pings, sent every 20 seconds.

        - Close codes: `1011` a feed failed, `1001` restart or missed pings,
        `1003` binary frame. Reconnect and resubscribe; nothing is replayed.
      operationId: websocketConnection
      responses:
        '101':
          description: The connection is upgraded to a WebSocket.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
        '400':
          description: >-
            The request carries a query string or a body, or signs with both
            `API-Nonce` and `API-Timestamp`.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
        '401':
          description: The credentials are missing or invalid.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
        '403':
          description: The path is wrong, or the request is not a WebSocket upgrade.
        '429':
          description: >-
            The account already holds its maximum number of connections, or the
            server is at capacity. Close a connection or retry later.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
        '500':
          description: An internal error prevented the connection.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
        '503':
          description: >-
            The service is starting, shutting down or cannot verify the
            credentials right now. Retry later.
          headers:
            X-Trace-Id:
              $ref: '#/components/headers/TraceId'
      security:
        - ApiKey: []
          ApiSign: []
          ApiTimestamp: []
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >
            import WebSocket from "ws";


            // Sign an empty GET /v1 request as the Authentication guide
            describes.

            const headers = sign({ method: "GET", path: "/v1", body: "" });

            const ws = new WebSocket("wss://ws.sandbox.services.payward.com/v1",
            { headers });


            ws.on("open", () => ws.send(JSON.stringify({
                method: "subscribe",
                params: { channel: "ticker", symbol: ["PF_XBTUSD"], asset_type: "perpetual", country: "DE" },
                req_id: 1,
              })));
            ws.on("message", (data) => console.log(JSON.parse(data)));
        - lang: python
          label: Python
          source: |
            import asyncio
            import json

            from websockets.asyncio.client import connect


            async def main():
                # Sign an empty GET /v1 request as the Authentication guide describes.
                headers = sign(method="GET", path="/v1", body="")
                async with connect("wss://ws.sandbox.services.payward.com/v1", additional_headers=headers) as ws:
                    await ws.send(json.dumps({"method": "subscribe", "params": {"channel": "ticker", "symbol": ["PF_XBTUSD"], "asset_type": "perpetual", "country": "DE"}, "req_id": 1}))
                    async for message in ws:
                        print(json.loads(message))


            asyncio.run(main())
components:
  headers:
    TraceId:
      description: Trace identifier for the request. Include it when contacting support.
      schema:
        type: string
        example: 4bf92f3577b34da6a3ce929d0e0e4736
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: Your public API key. Identifies the partner making the request.
    ApiSign:
      type: apiKey
      in: header
      name: API-Sign
      description: HMAC signature over the request, computed with your API secret.
    ApiTimestamp:
      type: apiKey
      in: header
      name: API-Timestamp
      description: >-
        Time the request was signed, as Unix milliseconds. Included in the
        request signature. Requests signed too far from the server's time are
        rejected.

````