API Introduction

The SohoPay API is a REST API over HTTPS with JSON request and response bodies. This page covers the conventions shared by every endpoint; the per-endpoint pages in the sidebar are generated from the OpenAPI spec and include an interactive playground.

Base URLs

Environment	Base URL	Chain
Sandbox	`https://api-sandbox.sohopay.xyz/v1`	Base Sepolia
Mainnet	`https://api.sohopay.xyz/v1`	Base

The environments are fully isolated — keys, agents, and data never cross between them. See Environment Setup for configuration details.

Authentication

Authenticate with an API key in the Authorization header:

curl https://api-sandbox.sohopay.xyz/v1/agents \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Sandbox keys start with sk_test_, mainnet keys with sk_live_. Missing or invalid keys return 401 INVALID_API_KEY. Full key lifecycle — generation, storage, rotation — is covered in Authentication & Security.

Rate limiting

Every response includes rate-limit state:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests left in the window
`Retry-After`	Seconds to wait — present only on `429` responses

When you exceed the limit the API returns 429 with code RATE_LIMITED. Wait the number of seconds in Retry-After before retrying; retrying sooner extends the penalty. Per-agent transaction limits are enforced separately by the Policy Service — see Rate Limits.

Errors

Every error response uses one envelope:

{
  "error": {
    "code": "INSUFFICIENT_CREDIT",
    "message": "Agent agt_7d1e5b2f has 3.50 USDC available; order requires 5.00.",
    "request_id": "req_a1b2c3d4"
  }
}

code — a stable machine-readable string. Branch on this, never on message.
message — human-readable detail; wording may change without notice.
request_id — include it in any support request so the team can trace the call.

The complete code table with recovery steps is in the error reference.

Idempotency

All POST endpoints accept an Idempotency-Key header. Send a unique key (a UUID works) with each logical operation; if the request is retried — a timeout, a network blip, a crashed worker — the API returns the original result instead of executing twice.

curl -X POST https://api-sandbox.sohopay.xyz/v1/orders \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Idempotency-Key: 4f7c2e9a-1b3d-4c5e-8f6a-7d8e9f0a1b2c" \
  -H "Content-Type: application/json" \
  -d '{"merchant_id": "mch_1a2b3c4d", "agent_id": "agt_7d1e5b2f", "amount": "5.00"}'

Keys are retained for 24 hours; after that a reused key is treated as a new request. Always set an idempotency key on payment and order creation — it makes retry-on-timeout safe.

Generate the idempotency key before the first attempt and reuse it on every retry of that operation. Generating a fresh key per retry defeats the purpose.

Pagination

List endpoints use cursor pagination with two query parameters:

limit — items per page (default 20, max 100)
cursor — opaque token from the previous page

curl "https://api-sandbox.sohopay.xyz/v1/settlements?limit=50&cursor=eyJpZCI6InN0bF8wMWEifQ" \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

{
  "data": [ { "settlement_id": "stl_01b2c3d4", "...": "..." } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InN0bF8wMWIifQ"
}

Iterate until has_more is false. Cursors are opaque — never parse or construct them.

Versioning

The current API version is v1, encoded in the URL path. Backwards-compatible changes — new fields, new endpoints, new webhook event types — ship to v1 without notice, so write parsers that tolerate unknown fields. Breaking changes get a new version path (e.g. /v2), and the previous version enters a 6-month deprecation window with dates announced by email and in the beta Slack channel. Nothing breaks under a version path you’ve pinned.

SohoPay is pre-mainnet; v1 is the only version and no deprecations are scheduled.

Interactive playground

The endpoint pages in the sidebar are generated from the OpenAPI spec at /api-reference/openapi.json. Each one includes an interactive playground — paste a sandbox key, edit the request body, and send real calls against the sandbox without leaving the docs. You can also import the spec into Postman or Insomnia; see OpenAPI Tools.

Next steps

Error Reference

Every error code with status, cause, and recovery.

Webhook Events

Event catalog, payloads, and signature verification.

TypeScript SDK

Skip raw HTTP with the official SDK.

Overview

Endpoints

API Introduction

Base URLs

Authentication

Rate limiting

Errors

Idempotency

Versioning

Interactive playground

Next steps

Error Reference

Webhook Events

TypeScript SDK

​Base URLs

​Authentication

​Rate limiting

​Errors

​Idempotency

​Pagination

​Versioning

​Interactive playground

​Next steps

Error Reference

Webhook Events

TypeScript SDK

Base URLs

Authentication

Rate limiting

Errors

Idempotency

Pagination

Versioning

Interactive playground

Next steps