API Reference

This document outlines the planned API architecture for StyxPay's backend services.

Note: This is a planned architecture. The frontend currently uses demo/mock data.

Overview

The StyxPay API provides programmatic access to user accounts, transactions, cards, and authorization policies.

Base URL: https://api.styxpay.app/v1

Authentication: Bearer tokens (JWT)

Format: JSON

Authentication

POST /auth/signup

Create a new user account.

Request:

{
  "email": "[email protected]",
  "password": "securePassword123",
  "name": "John Doe"
}

Response (201):

{
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "John Doe",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

POST /auth/login

Authenticate and receive access token.

Request:

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

---

User Accounts

GET /users/me

Get current user profile.

Headers:

Authorization: Bearer {token}

Response (200):

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "createdAt": "2025-01-10T12:00:00Z",
  "kycStatus": "verified",
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

---

GET /users/me/balance

Get account balances.

Response (200):

{
  "total": 124592.00,
  "currency": "USD",
  "breakdown": {
    "available": 124592.00,
    "pending": 0.00,
    "locked": 0.00
  },
  "assets": [
    {
      "symbol": "USDC",
      "amount": 124592.00,
      "usdValue": 124592.00
    }
  ]
}

---

Transactions

GET /transactions

List user transactions.

Query Parameters:

• limit (number) - Results per page (default: 20, max: 100)

• offset (number) - Pagination offset

• status (string) - Filter by status: pending, completed, failed

• type (string) - Filter by type: deposit, withdrawal, payment

• startDate (ISO 8601) - Filter from date

• endDate (ISO 8601) - Filter to date

Example:

GET /transactions?limit=10&status=completed

Response (200):

{
  "data": [
    {
      "id": "txn_xyz789",
      "type": "deposit",
      "amount": 4200.00,
      "currency": "USD",
      "status": "completed",
      "description": "Deposit from Coinbase",
      "createdAt": "2025-01-10T10:23:00Z",
      "metadata": {
        "source": "coinbase",
        "reference": "CB123456"
      }
    },
    {
      "id": "txn_abc456",
      "type": "payment",
      "amount": -240.50,
      "currency": "USD",
      "status": "completed",
      "description": "Amazon Web Services",
      "createdAt": "2025-01-09T16:00:00Z",
      "cardLast4": "4921"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

---

GET /transactions/:id

Get transaction details.

Response (200):

{
  "id": "txn_xyz789",
  "type": "deposit",
  "amount": 4200.00,
  "currency": "USD",
  "status": "completed",
  "description": "Deposit from Coinbase",
  "createdAt": "2025-01-10T10:23:00Z",
  "updatedAt": "2025-01-10T10:23:15Z",
  "metadata": {
    "source": "coinbase",
    "reference": "CB123456"
  },
  "zkProof": "proof_hash_here"
}

---

Virtual Cards

GET /cards

List user's cards.

Response (200):

{
  "data": [
    {
      "id": "card_123",
      "last4": "4921",
      "status": "active",
      "type": "virtual",
      "name": "Primary Card",
      "monthlyLimit": 25000.00,
      "monthlySpent": 3250.00,
      "createdAt": "2024-12-01T00:00:00Z"
    },
    {
      "id": "card_456",
      "last4": "5921",
      "status": "active",
      "type": "virtual",
      "name": "Subscriptions",
      "monthlyLimit": 500.00,
      "monthlySpent": 125.00,
      "createdAt": "2024-12-15T00:00:00Z"
    }
  ]
}

---

POST /cards

Create a new virtual card.

Request:

{
  "name": "Shopping Card",
  "monthlyLimit": 5000.00,
  "authPolicy": {
    "type": "whitelist",
    "merchants": ["amazon.com", "walmart.com"],
    "categories": ["retail", "grocery"]
  }
}

Response (201):

{
  "id": "card_789",
  "number": "5555555555554444",
  "cvv": "123",
  "expiry": "12/28",
  "last4": "4444",
  "status": "active",
  "type": "virtual",
  "name": "Shopping Card",
  "monthlyLimit": 5000.00,
  "monthlySpent": 0.00,
  "createdAt": "2025-01-10T12:00:00Z"
}

---

PUT /cards/:id

Update card settings.

Request:

{
  "name": "Updated Name",
  "monthlyLimit": 10000.00,
  "status": "active"
}

Response (200):

{
  "id": "card_789",
  "last4": "4444",
  "status": "active",
  "name": "Updated Name",
  "monthlyLimit": 10000.00,
  "updatedAt": "2025-01-10T13:00:00Z"
}

---

DELETE /cards/:id

Deactivate a card.

Response (200):

{
  "id": "card_789",
  "status": "inactive",
  "deactivatedAt": "2025-01-10T14:00:00Z"
}

---

Authorization Policies

GET /policies

Get authorization policies for cards.

Response (200):

{
  "data": [
    {
      "id": "pol_abc",
      "cardId": "card_123",
      "type": "whitelist",
      "dailyLimit": 5000.00,
      "currency": "USDC",
      "merchants": ["amazon.com", "uber", "apple_services"],
      "zkProofRequired": true,
      "createdAt": "2024-12-01T00:00:00Z"
    }
  ]
}

---

POST /policies

Create authorization policy.

Request:

{
  "cardId": "card_123",
  "type": "whitelist",
  "dailyLimit": 5000.00,
  "currency": "USDC",
  "merchants": ["amazon.com", "uber"],
  "zkProofRequired": true
}

Response (201):

{
  "id": "pol_xyz",
  "cardId": "card_123",
  "type": "whitelist",
  "dailyLimit": 5000.00,
  "currency": "USDC",
  "merchants": ["amazon.com", "uber"],
  "zkProofRequired": true,
  "createdAt": "2025-01-10T12:00:00Z"
}

---

Analytics

GET /analytics/spending

Get spending analytics.

Query Parameters:

• period - day, week, month, year

• startDate (ISO 8601)

• endDate (ISO 8601)

Response (200):

{
  "period": "month",
  "totalSpent": 8421.50,
  "totalDeposits": 12000.00,
  "netFlow": 3578.50,
  "categories": [
    {
      "name": "Subscriptions",
      "amount": 240.50,
      "percentage": 2.85
    },
    {
      "name": "Retail",
      "amount": 6500.00,
      "percentage": 77.18
    }
  ],
  "dailyData": [
    {
      "date": "2025-01-01",
      "spent": 125.00,
      "deposits": 0.00
    }
    // ... more days
  ]
}

---

Webhooks

POST /webhooks

Register a webhook endpoint.

Request:

{
  "url": "https://your-app.com/webhooks/styxpay",
  "events": [
    "transaction.completed",
    "transaction.failed",
    "card.created",
    "card.limit_exceeded"
  ],
  "secret": "whsec_your_secret_here"
}

Response (201):

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/styxpay",
  "events": [
    "transaction.completed",
    "transaction.failed",
    "card.created",
    "card.limit_exceeded"
  ],
  "status": "active",
  "createdAt": "2025-01-10T12:00:00Z"
}

Webhook Payload Example

{
  "id": "evt_xyz789",
  "type": "transaction.completed",
  "createdAt": "2025-01-10T10:23:15Z",
  "data": {
    "transaction": {
      "id": "txn_xyz789",
      "type": "deposit",
      "amount": 4200.00,
      "currency": "USD",
      "status": "completed"
    }
  }
}

---

Error Responses

All errors follow this format:

{
  "error": {
    "code": "invalid_request",
    "message": "Email is required",
    "details": {
      "field": "email",
      "reason": "missing"
    }
  }
}

Error Codes

• invalid_request - Invalid parameters (400)

• unauthorized - Missing or invalid token (401)

• forbidden - Insufficient permissions (403)

• not_found - Resource not found (404)

• rate_limit_exceeded - Too many requests (429)

• internal_error - Server error (500)

---

Rate Limiting

• Default: 100 requests per minute per user

• Burst: 20 requests per second

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1641811200

---

SDKs

JavaScript/TypeScript

npm install @styxpay/sdk

import { StyxPay } from '@styxpay/sdk'

const client = new StyxPay('your_api_key')

// Get balance
const balance = await client.users.getBalance()

// Create card
const card = await client.cards.create({
  name: 'Shopping Card',
  monthlyLimit: 5000
})

// List transactions
const transactions = await client.transactions.list({
  limit: 10,
  status: 'completed'
})

Python

pip install styxpay

from styxpay import StyxPay

client = StyxPay('your_api_key')

# Get balance
balance = client.users.get_balance()

# Create card
card = client.cards.create(
    name='Shopping Card',
    monthly_limit=5000
)

# List transactions
transactions = client.transactions.list(
    limit=10,
    status='completed'
)

---

Related Documentation

• Getting Started

• Technical Architecture

• Deployment Guide

---

Last Updated: January 2026