Skip to main content
The Saturn API is organized around REST. All endpoints are under /v1 and return JSON.

​
Base URL

https://api.saturn-pay.com

​
Authentication

Authenticate using Bearer token in the Authorization header: 
curl https://api.saturn-pay.com/v1/wallet \
  -H "Authorization: Bearer sk_agt_your_key_here"

​
Endpoints

​
Unauthenticated

MethodPathDescription
POST/v1/signupCreate account + agent, get API key
GET/healthHealth check

​
Capabilities

MethodPathDescription
GET/v1/capabilitiesList all capabilities with providers and pricing
GET/v1/capabilities/:capabilityGet capability details
POST/v1/capabilities/:capabilityExecute a capability

​
Proxy (Direct Service Access)

MethodPathDescription
GET/v1/servicesList available services
GET/v1/services/:slugGet service details and pricing
POST/v1/proxy/:slugProxy a request to a service

​
Agents

MethodPathDescription
GET/v1/agentsList agents
POST/v1/agentsCreate agent (returns API key)
GET/v1/agents/:idGet agent
PATCH/v1/agents/:idUpdate agent

​
Policies

MethodPathDescription
GET/v1/agents/:id/policyGet agent policy
PUT/v1/agents/:id/policyReplace policy
PATCH/v1/agents/:id/policyUpdate policy fields

​
Wallets

MethodPathDescription
GET/v1/walletGet current agent’s wallet
POST/v1/wallet/fundCreate Lightning invoice to fund wallet (sats)
POST/v1/wallet/fund-cardCreate Stripe checkout to fund wallet (USD)
GET/v1/wallet/invoicesList invoices
GET/v1/wallet/transactionsList transactions
GET/v1/agents/:id/walletGet agent’s wallet (account owner)

​
Admin

MethodPathDescription
GET/v1/admin/statsDashboard statistics
GET/v1/admin/agentsList all agents with balances
GET/v1/admin/transactionsList all transactions
GET/v1/admin/audit-logsQuery audit logs
GET/v1/admin/service-healthService health metrics
GET/v1/admin/rateCurrent BTC/USD rate

​
Registry (Community Services)

MethodPathDescription
POST/v1/registry/submitSubmit a service for review
GET/v1/registry/submissionsList your submissions

​
Error Format

All errors follow a consistent format: 
{
  "error": {
    "code": "BUDGET_EXCEEDED",
    "message": "Daily budget exceeded: $1.00 limit reached",
    "details": {
      "dailySpent": 100,
      "dailyCap": 100,
      "quotedCost": 15
    }
  }
}
See Error Handling for detailed error documentation.

​
Rate Limits

  • 100 requests per minute per agent
  • 1000 requests per minute per account
  • Rate limit headers included in responses
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000