Get Points

All requests require an API key via the X-API-Key header. Reads accept a publishable key (pk_live_) from browser code or a secret key (sk_live_) from your backend. See Authentication for details.

Overview

GET /v2/streams/points returns points. Use orgId to narrow results to a specific organization. This endpoint is useful when your integration supports point-based streams and needs to list the point assets available for stream creation or reporting. If your organization only creates token-based streams with rewardToken, you do not need to call this endpoint.

Endpoint

curl -X GET "https://earn.turtle.xyz/v2/streams/points?symbol=PTS" \
  -H "X-API-Key: sk_live_xxxxx"

const response = await fetch(
  'https://earn.turtle.xyz/v2/streams/points?symbol=PTS',
  { headers: { 'X-API-Key': process.env.TURTLE_API_KEY! } }
);

const data = await response.json();

Query Parameters

uuid

Optional point identifier.

uuid

Optional organization identifier. When provided, returns only points belonging to that organization.

string

Optional point symbol filter.

string

Optional point name filter.

Response Example

{
  "points": [
    {
      "id": "7ff13cf6-53d0-4f3e-bd1a-e8eab6db4cf1",
      "orgId": "9f51b66a-d13a-4b55-8515-ae6e4ef7cf25",
      "symbol": "PTS",
      "name": "Partner Points",
      "decimals": 18,
      "logoUrl": "https://cdn.example.com/points/pts.png",
      "createdAt": "2026-03-01T00:00:00Z",
      "updatedAt": "2026-03-01T00:00:00Z"
    }
  ]
}

Response Fields

Point[]

Array of points matching the provided filters.

See Create Point for the full Point schema.

Important Notes

Points are only relevant for point-based streams

Points are used when creating streams that use pointId as the reward source. They are not required for streams that use rewardToken.

Filters are optional and combinable

You can query by id, orgId, symbol, name, or any combination supported by your integration needs.

Error Handling

Missing or invalid API key

Status Code: 401 Unauthorized

{
  "error": "API key required. Pass it via the X-API-Key header."
}

A key that is present but invalid, inactive, or expired also returns 401, with "Invalid API key", "API key is inactive", or "API key has expired".Solution: Send a valid key on the X-API-Key header.

Origin not allowed

Status Code: 403 Forbidden

{
  "error": "Origin not allowed for this API key"
}

Publishable keys (pk_live_) are checked against the origin allowlist configured on the key. A request from an origin that is not on the list — including a server-side call that sends no Origin or Referer header — is rejected.Solution: Call from an allowlisted browser origin, or use a secret key (sk_live_) from your backend.

Rate limit exceeded

Status Code: 429 Too Many Requests

{
  "error": "Rate limit exceeded"
}

Usage is metered per key, hourly and monthly. Every response carries the hourly budget in the X-RateLimit-* headers; keys with a monthly limit also get X-Monthly-* headers. A monthly overrun returns "Monthly usage limit exceeded" instead.Solution: Back off until the window resets — hourly limits also return Retry-After — or ask the Turtle team for a higher limit. See Rate limits.

Unexpected internal error

Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.

Get Started

Products

Reference

Overview

Endpoint

Response Example

Response Fields

Important Notes

Error Handling

​Overview

​Endpoint

​Response Example

​Response Fields

​Important Notes

​Error Handling

Overview

Endpoint

Response Example

Response Fields

Important Notes

Error Handling