API Overview

API Version: v1 (Private Beta) · Status: Accepting waitlist applications · Base URL: https://api.stablegenius.co/v1

The Stable Genius API is a REST API that uses JSON for request and response bodies, standard HTTP status codes, and bearer token authentication.

Base URL

https://api.stablegenius.co/v1

All API requests must be made over HTTPS.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_test_abc123

See Authentication for details on API key types and management.

Request Format

All POST/PUT requests must include Content-Type: application/json
Request bodies are JSON objects
Query parameters are used for filtering on GET requests

Response Format

All responses follow a consistent structure:

{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  // ... additional fields
}

List endpoints return paginated results:

{
  "object": "list",
  "data": [ /* array of objects */ ],
  "has_more": true,
  "total_count": 142
}

Pagination

List endpoints support cursor-based pagination:

Parameter	Type	Description
`limit`	`integer`	Number of results per page. Default: 25. Max: 100.
`starting_after`	`string`	Cursor for forward pagination. Pass the `id` of the last item in the previous page.
`ending_before`	`string`	Cursor for backward pagination.

Errors

Errors return standard HTTP status codes with a JSON body:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Amount must be greater than 0",
    "param": "amount",
    "code": "amount_too_small"
  }
}

Status Code	Description
`200`	Success
`201`	Created
`400`	Bad request — invalid parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — valid key but insufficient permissions
`404`	Not found
`409`	Conflict — duplicate resource (e.g., idempotency key match)
`422`	Unprocessable — request understood but cannot be processed
`429`	Rate limited — too many requests
`500`	Internal server error

Rate Limits

Environment	Limit
Sandbox (`sk_test_*`)	100 requests/minute
Production (`sk_live_*`)	1,000 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1711929600

Versioning

The API is versioned via the URL path (/v1/). Breaking changes will only be introduced in new major versions. Non-breaking additions (new fields, new endpoints) may be added to the current version at any time. Set the X-API-Version header to pin your integration to a specific API version:

X-API-Version: 2026-04-01

Idempotency

POST endpoints support idempotency via the idempotency_key field in the request body. Resubmitting a request with the same key within 24 hours returns the original response instead of creating a duplicate.

Overview

Payment Intents

Transactions

Merchants

Webhooks

API Overview

API Overview

Base URL

Authentication

Request Format

Response Format

Errors

Rate Limits

Versioning

Idempotency

​API Overview

​Base URL

​Authentication

​Request Format

​Response Format

​Pagination

​Errors

​Rate Limits

​Versioning

​Idempotency

API Overview

Base URL

Authentication

Request Format

Response Format

Pagination

Errors

Rate Limits

Versioning

Idempotency