📡 HeavensLive REST API

Authenticate and receive a JWT token. Token expires in 24 hours.

POST /api/auth/login
Content-Type: application/json

{"email": "user@example.com", "password": "yourpassword"}

// Response 200
{"success": true, "token": "eyJhbG...", "user": {"id": "...", "email": "..."}}

Register a new account. Optional referralCode credits the referrer.

POST /api/auth/register
{"email": "new@example.com", "password": "min8chars", "fullName": "Name", "referralCode": "abc123"}

Browse marketplace listings with filters, search, and pagination.

GET /api/shop/listings?category=electronics&sort=price_low&lang=ja&limit=20

// Response
{"listings": [{
  "id": "uuid", "title": "日本語タイトル", "description": "...",
  "price_cents": 89900, "type": "mall", "category": "electronics",
  "location_city": "Tokyo", "images": ["url1"], "currency": "USD", "accepted_currencies": ["USD","EUR","Credon-BTC"], "created_at": "2026-..."
}], "pagination": {"page": 1, "limit": 20, "total": 42, "totalPages": 3}}

Get single listing details. Add ?lang=fa for translated content. Response includes currency and accepted_currencies fields.

Get top-level categories with listing counts. Add ?lang=fr for translated names.

GET /api/shop/categories?lang=zh
// Response
{"categories": [{"slug": "electronics", "name": "电子产品", "icon": "📱", "count": 9, "subcategory_count": 1}]}

Get subcategories under a parent category.

GET /api/shop/categories/subcategories/electronics?lang=ko

Create a new marketplace listing. Requires authentication.

POST /api/shop/listings
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "mall",
  "title": "Vintage Record Player",
  "description": "Fully restored...",
  "category": "electronics",
  "price_cents": 49900,
  "currency": "USD",
  "accepted_currencies": ["USD", "EUR", "Credon-BTC"],
  "quantity_available": 1,
  "duration": "2weeks",
  "location_city": "London",
  "location_country": "GB",
  "is_featured": false,
  "featured_payment_method": null
}

Get public store profile and listings by store slug.

GET /api/shop/stores/bryans-marketplace
// Response
{"store": {"store_name": "...", "slug": "...", "description": "..."}, "listings": [...]}

Get live exchange rates for all 84 Credon currencies and fiat pairs. Rates update every 30 minutes from Frankfurter API and CoinGecko. Used for currency display and cross-currency payments.

GET /api/wallet/exchange-rates
// Response
{"rates": {"Credon-USD": {"rate": 1.0}, "Credon-BTC": {"rate": 0.000012},
            "EUR": {"rate": 0.92}, "JPY": {"rate": 149.5}}, "updated_at": "..."}

Get UI translation strings for a language. Used by the frontend for chrome (buttons, nav, filters).

GET /locales/shop-fa.json  // Farsi
GET /locales/shop-ja.json  // Japanese
// 16 languages supported: ar, de, en, es, fa, fr, hi, ja, ko, pt, ru, sv, tl, tr, ur, vi, zh

API keys provide higher rate limits (1000 req/min) for production integrations. Generate keys from your Settings page.

Include your key in requests:

Authorization: Bearer hl_xxxxxxxxxxxxxxxx

Or as a query parameter:

GET /api/shop/listings?api_key=hl_xxxxxxxxxxxxxxxx

Complete a purchase. Wallet-first: deducts from Credon balance if sufficient, otherwise redirects to PayPal. No errors — seamless fallback. Shipping always USD.

POST /api/shop/checkout
Authorization: Bearer {token}

{
  "cartItems": [{"listing_id":"uuid","quantity":1}],
  "shippingAddress": {"street":"...","city":"...","zip":"..."},
  "deliveryMethod": "shipping",
  "paymentMethod": "credon_wallet",
  "shippingCostCents": 500
}

// Response 200 — Credon wallet (sufficient balance)
{"success":true,"paymentMethod":"credon_wallet","deducted":1500,"shippingCurrency":"USD"}

// Response 200 — PayPal redirect (insufficient balance)
{"success":true,"paymentMethod":"paypal","approvalUrl":"https://www.paypal.com/...","shippingCurrency":"USD"}

Request a password reset link. Always returns success to prevent email enumeration.

POST /api/auth/forgot-password
{"email":"user@example.com"}
// Response 200
{"success":true,"message":"If that email exists, a reset link has been sent."}

Set a new password using a valid reset token.

POST /api/auth/reset-password
{"token":"abc123...","password":"newpassword123"}
// Response 200
{"success":true,"message":"Password updated. You can now sign in."}

Get current user's subscription plan and featured listing limits. Requires auth.

GET /api/shop/subscriptions/my-plan
Authorization: Bearer {token}
// Response
{"plan_name":"Pro","limits":{"featuredListings":5},"usage":{"currentFeatured":2}}

List all available subscription plans (public).

Subscribe to a plan. Supports PayPal and Credon Wallet payment in any clone currency.

POST /api/shop/subscriptions/subscribe
Authorization: Bearer {token}

{
  "planId": "pro-monthly",
  "billingCycle": "monthly",
  "paymentMethod": "credon_wallet",
  "currency": "Credon-EUR"
}

// Response 200 — Credon wallet (sufficient balance)
{"success":true,"paymentMethod":"credon_wallet","message":"Pro plan activated! Paid $9.99 from Credon wallet.","plan":"Pro","deducted":999}

// Response 200 — PayPal redirect (insufficient balance)
{"success":true,"paymentMethod":"paypal","approvalUrl":"https://www.paypal.com/...","plan":"Pro"}

Get current user's Credon wallet balance. Requires auth.

GET /api/wallet/balance
Authorization: Bearer {token}
// Response
{"balance_cents":100000,"balance_usd":"1000.00"}

When creating a listing, include is_featured: true and a featured_payment_method. Subscription users get free featured slots based on plan limits. Others choose payment.

{
  "is_featured": true,
  "featured_payment_method": "subscription",
  // or "paypal" / "credon_wallet" if no subscription
}

All errors return appropriate HTTP status codes with a JSON body:

// 400 Bad Request
{"error": "Amount required"}

// 401 Unauthorized
{"error": "Invalid or expired token"}

// 403 Forbidden
{"error": "Not authorized"}

// 404 Not Found
{"error": "Listing not found"}

// 429 Rate Limited
{"error": "Too many requests"}

// 500 Server Error
{"error": "Internal server error"}