Get Funding Payments (WebSocket)

Retrieve detailed funding payment history and statistics for the authenticated subaccount through the WebSocket connection. This endpoint provides user-specific funding data including payments received, paid, and net funding across all positions.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/trade

Request

Request Format

{
  "id": "funding-payments-1",
  "method": "post",
  "params": {
    "action": "getFundingPayments",
    "subAccountId": "1867542890123456789",
    "symbol": "BTC-USDT",
    "startTime": 1735603200000,
    "endTime": 1735689600000,
    "limit": 100,
    "expiresAfter": 1735689900,
    "signature": {
      "v": 28,
      "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  }
}

Parameters

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Client-generated unique request identifier
`method`	string	Yes	Must be `"post"`
`params`	object	Yes	Contains all parameters for the request

Params Object

Parameter	Type	Required	Description
`action`	string	Yes	Must be `"getFundingPayments"`
`subAccountId`	string	Yes	Subaccount identifier
`symbol`	string	No	Filter by specific trading pair (e.g., `"BTC-USDT"`)
`startTime`	integer	No	Start timestamp for filtering (milliseconds). Cannot be more than 30 days in the past. When omitted, defaults to `now − 30 days`.
`endTime`	integer	No	End timestamp for filtering (milliseconds). If `endTime` is older than 30 days and `startTime` is not provided, the request is rejected.
`limit`	integer	No	Maximum number of records to return. Default: 100. Maximum: 1000.
`expiresAfter`	integer	No	Optional expiration timestamp in seconds
`signature`	object	Yes	EIP-712 signature using `SubAccountAction` type

Important Notes:

This endpoint uses SubAccountAction EIP-712 type (no nonce required)
For deposit/withdrawal history, use Get Balance Updates

EIP-712 Signature

const domain = {
  name: "Synthetix",
  version: "1",
  chainId: 1,
  verifyingContract: "0x0000000000000000000000000000000000000000"
};
 
const types = {
  SubAccountAction: [
    { name: "subAccountId", type: "uint256" },
    { name: "action", type: "string" },
    { name: "expiresAfter", type: "uint256" }
  ]
};
 
const message = {
  subAccountId: "1867542890123456789",
  action: "getFundingPayments",
  expiresAfter: 0
};
 
const signature = await signer._signTypedData(domain, types, message);

Response Format

Success Response

{
  "id": "funding-payments-1",
  "status": 200,
  "result": {
    "summary": {
      "totalFundingReceived": "125.75000000",
      "totalFundingPaid": "89.25000000",
      "netFunding": "36.50000000",
      "totalPayments": "247",
      "averagePaymentSize": "0.87044534"
    },
    "fundingHistory": [
      {
        "paymentId": "fp_1958787130134106112",
        "symbol": "BTC-USDT",
        "positionSize": "2.50000000",
        "fundingRate": "0.00001250",
        "payment": "-1.12500000",
        "timestamp": 1735689600000,
        "paymentTime": 1735689600000,
        "fundingTimestamp": 1735689600000,
        "fundingTime": 1735689600000
      },
      {
        "paymentId": "fp_1958787130134106111",
        "symbol": "ETH-USDT",
        "positionSize": "-5.00000000",
        "fundingRate": "-0.00002100",
        "payment": "3.15000000",
        "timestamp": 1735661200000,
        "paymentTime": 1735661200000,
        "fundingTimestamp": 1735661200000,
        "fundingTime": 1735661200000
      }
    ]
  }
}

Empty Result

{
  "id": "funding-payments-1",
  "status": 200,
  "result": {
    "summary": {
      "totalFundingReceived": "0",
      "totalFundingPaid": "0",
      "netFunding": "0",
      "totalPayments": "0",
      "averagePaymentSize": "0"
    },
    "fundingHistory": []
  }
}

Error Response

{
  "id": "funding-payments-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "Invalid time range parameters"
  }
}

Response Fields

Summary Object

Field	Type	Description
`totalFundingReceived`	string	Total funding payments received
`totalFundingPaid`	string	Total funding payments paid
`netFunding`	string	Net funding (received - paid)
`totalPayments`	string	Total number of funding payments
`averagePaymentSize`	string	Average payment size (absolute value)

Funding History Object

Field	Type	Description
`paymentId`	string	Unique identifier for the funding payment
`symbol`	string	Trading pair symbol
`positionSize`	string	Position size at funding time (signed)
`fundingRate`	string	Funding rate applied (1-hour rate)
`payment`	string	Funding payment amount (negative = paid out)
`timestamp`	integer	DEPRECATED - Use `paymentTime` instead
`paymentTime`	integer	When payment was processed
`fundingTimestamp`	integer	DEPRECATED - Use `fundingTime` instead
`fundingTime`	integer	Funding period timestamp

Payment Calculation

Formula: Payment = Position Size × Funding Rate × Mark Price

Positive payment: Funding received
Negative payment: Funding paid
Long positions: Pay when funding rate is positive
Short positions: Receive when funding rate is positive

Code Examples

Get All Funding Payments

{
  "id": "all-funding",
  "method": "post",
  "params": {
    "action": "getFundingPayments",
    "subAccountId": "1867542890123456789",
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Filter by Symbol

{
  "id": "btc-funding",
  "method": "post",
  "params": {
    "action": "getFundingPayments",
    "subAccountId": "1867542890123456789",
    "symbol": "BTC-USDT",
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Filter by Time Range

{
  "id": "time-range-funding",
  "method": "post",
  "params": {
    "action": "getFundingPayments",
    "subAccountId": "1867542890123456789",
    "startTime": 1735603200000,
    "endTime": 1735689600000,
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Implementation Example

class FundingPaymentsQuery {
  constructor(ws, signer) {
    this.ws = ws;
    this.signer = signer;
    this.pendingRequests = new Map();
  }
 
  async getFundingPayments(options = {}) {
    const {
      subAccountId,
      symbol = null,
      startTime = null,
      endTime = null,
      limit = 100,
      expiresAfter = 0
    } = options;
 
    const signature = await this.signSubAccountAction(subAccountId, "getFundingPayments", expiresAfter);
 
    const request = {
      id: `funding-payments-${Date.now()}`,
      method: "post",
      params: {
        action: "getFundingPayments",
        subAccountId,
        limit,
        expiresAfter,
        signature
      }
    };
 
    if (symbol) request.params.symbol = symbol;
    if (startTime) request.params.startTime = startTime;
    if (endTime) request.params.endTime = endTime;
 
    return this.sendRequest(request);
  }
 
  async signSubAccountAction(subAccountId, action, expiresAfter = 0) {
    const domain = {
      name: "Synthetix",
      version: "1",
      chainId: 1,
      verifyingContract: "0x0000000000000000000000000000000000000000"
    };
 
    const types = {
      SubAccountAction: [
        { name: "subAccountId", type: "uint256" },
        { name: "action", type: "string" },
        { name: "expiresAfter", type: "uint256" }
      ]
    };
 
    const message = {
      subAccountId: BigInt(subAccountId),
      action,
      expiresAfter: BigInt(expiresAfter)
    };
 
    const sig = await this.signer.signTypedData(domain, types, message);
    const { v, r, s } = ethers.Signature.from(sig);
    return { v, r, s };
  }
 
  sendRequest(request) {
    return new Promise((resolve, reject) => {
      this.pendingRequests.set(request.id, { resolve, reject });
      this.ws.send(JSON.stringify(request));
 
      setTimeout(() => {
        if (this.pendingRequests.has(request.id)) {
          this.pendingRequests.delete(request.id);
          reject(new Error('Request timeout'));
        }
      }, 10000);
    });
  }
}
 
// Usage: Analyze funding performance
const query = new FundingPaymentsQuery(ws, signer);
const result = await query.getFundingPayments({
  subAccountId: "1867542890123456789",
  startTime: Date.now() - (30 * 24 * 60 * 60 * 1000) // Last 30 days
});
 
const netFunding = parseFloat(result.summary.netFunding);
console.log(`Net funding last 30 days: ${netFunding} USDT`);

Use Cases

Funding Performance Analysis

// Analyze funding performance over time
const fundingData = await query.getFundingPayments({
  subAccountId: "1867542890123456789",
  startTime: Date.now() - (30 * 24 * 60 * 60 * 1000) // Last 30 days
});
 
const netFunding = parseFloat(fundingData.summary.netFunding);
console.log(`Net funding last 30 days: ${netFunding} USDT`);

Position-Specific Funding

// Get funding for specific market
const btcFunding = await query.getFundingPayments({
  subAccountId: "1867542890123456789",
  symbol: "BTC-USDT"
});

Common Errors

Status	Error Code	Message	Solution
400	`VALIDATION_ERROR`	subAccountId is required	Provide a valid authenticated subaccount
400	`VALIDATION_ERROR`	invalid symbol	Use a valid symbol (e.g., `BTC-USDT`) from getMarkets
400	`VALIDATION_ERROR`	startTime must be less than endTime	Ensure `startTime` is strictly less than `endTime`
400	`VALIDATION_ERROR`	startTime must be a valid timestamp	Use a timestamp within the last year and not in the future
400	`VALIDATION_ERROR`	limit must not exceed 1000	Reduce the limit to 1000 or below
400	`INVALID_FORMAT`	Invalid request body	Check request structure and field types

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

Next Steps

Get Positions - Current positions
Get Balance Updates - Deposit/withdrawal history
Get Performance History - Overall performance
REST Alternative - REST API comparison