API reference

Authentication

Every authenticated endpoint expects a Bearer JWT in the Authorization header. Get a token from /auth/login using your account email + password - the same credentials you use on the storefront. Tokens last 7 days.

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

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "_id": "...", "username": "youruser", "email": "...", "role": "user" }
}

Pass the token as a Bearer header on every subsequent request:

curl https://market-api.gydrus.net/api/listings/mine \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "user": { "_id": "...", "username": "youruser", "email": "...", "role": "user", "coins": 0 }
}

Treat your token like a password - anyone holding it can act on your account until it expires. Rotate tokens regularly: log in again to get a fresh one, copy it into your script's secrets store, and discard the old one.

Errors

Every error response shares the same shape. The HTTP status is also set appropriately (400, 401, 403, …) so a basic HTTP client can branch on it without parsing JSON:

{
  "error": {
    "status": 400,
    "message": "Listing slug already in use",
    "details": null,
    "i18n": { "key": "apierr.slugTaken", "vars": null }
  }
}

Status codes you can expect:

• 400 — Validation error or business rule violation (missing field, slug already in use, insufficient funds, etc.)
• 401 — Missing, invalid or expired Bearer token
• 403 — The token is valid but your account does not have permission for this action
• 404 — The resource does not exist
• 409 — You are trying to create something that already exists (duplicate slug, duplicate verification submission, etc.)
• 429 — Rate limit exceeded - the response body includes retryAfterSec

Rate limits

Per-user limits apply on every write-heavy endpoint. When you hit one you get HTTP 429 with retryAfterSec in the body - wait that many seconds and retry.

• Listing creation: 20 per day
• Image uploads: 100 per day
• Order messages: 200 per day
• Disputes opened: 5 per day, max 5 open at once
• Wallet deposits: 10 per hour
• Reviews submitted: 50 per day

These are anti-abuse caps, not commercial limits - if your use case needs higher throughput (high-volume stock, bulk migration), contact support and we can raise your individual cap.

Listings

Listings are the core marketplace object. Every listing belongs to one game and one service category, has a price in minor units (cents), and may carry stock items (instant-delivery listings) or be a "service" listing the seller delivers manually. Title and description are localized maps - populate at least the default locale and you can add translations later.

{
  "items": [
    {
      "_id": "...",
      "slug": "ultimate-fortnite-account-3f9a",
      "title": { "en": "Ultimate Fortnite Account" },
      "description": { "en": "Includes 50 skins, full BP..." },
      "price": 4500,
      "stock": 3,
      "game": { "_id": "...", "name": "Fortnite", "slug": "fortnite", "imageUrl": "..." },
      "seller": { "_id": "...", "username": "progamer", "seller": { "rating": 4.9 } },
      "images": ["https://cdn.gydrus.net/..."]
    }
  ],
  "page": 1, "limit": 20, "total": 312, "pages": 16
}

{
  "game": "<game id>",
  "category": "account",
  "title": { "en": "Smurf account, Diamond rank" },
  "description": { "en": "EU server. Full mastery on top 10 champions..." },
  "defaultLocale": "en",
  "price": 3500,
  "stock": 5,
  "minQuantity": 1,
  "images": ["https://cdn.gydrus.net/abc.webp"],
  "attributes": { "server": "EUW", "rank": "diamond" },
  "deliveryType": "inventory",
  "deliveryTime": "instant",
  "deliveryInstructions": { "en": "Login details will be delivered automatically." }
}

{
  "_id": "...",
  "slug": "smurf-account-diamond-rank-3f9a1c",
  ...
}

{
  "price": 4000,
  "stock": 8
}

Stock items

Stock items are the credentials (account login, gift card code, etc.) attached to an instant-delivery listing. They are encrypted at rest with AES-256-GCM and revealed to the buyer only at the moment of purchase. The shape of each item is free-form JSON - your script decides what fields a buyer needs.

{
  "items": [
    { "_id": "...", "status": "available", "createdAt": "2026-...", "preview": "Account #1" }
  ]
}

{
  "items": [
    { "username": "[email protected]", "password": "...", "extra": "Recovery code abc123" },
    { "username": "[email protected]", "password": "...", "extra": "Recovery code def456" }
  ]
}

Orders

Orders represent a completed purchase. The buyer pays into escrow; you (the seller) deliver; after the escrow window closes the funds release to your wallet. You can communicate with the buyer through the order conversation thread.

{
  "body": "Hi! Just to confirm, the account is ready and will be delivered tonight."
}

Wallet

Your wallet holds your platform balance - earnings released from escrow, refunds received, manual top-ups. All amounts are in minor units (USD cents). Withdraw via the dedicated withdrawal flow.

{
  "wallet": { "_id": "...", "balance": 125000, "currency": "USD" },
  "transactions": [
    { "_id": "...", "type": "sale", "amount": 4500, "balanceAfter": 125000, "description": "Sale: ...", "createdAt": "..." }
  ],
  "escrow": { "held": 8000, "released": 0 }
}

Withdrawals

Withdrawals require an approved ID verification on file. You register a destination wallet once and then request withdrawals against it; an admin reviews each request before funds move.

{
  "method": "crypto",
  "crypto": { "currency": "USDT_TRC20", "address": "T...." }
}

{
  "amount": 50000,
  "walletId": "<id from /withdrawals/wallets>"
}

Image uploads

Use this endpoint to upload listing photos and avatars. The server validates the image, strips all metadata (EXIF/GPS/device), resizes to fit 2000×2000, and re-encodes to WebP. The returned URL is permanent - put it into Listing.images or User.avatarUrl.

{
  "url": "https://cdn.gydrus.net/1779286476998-c2dadb980629ce0a.webp"
}

For ID-verification documents (private), append ?visibility=private. The response then includes a key (the persistent reference to store) and a short-lived signed url for immediate preview.

Reference data

Read-mostly endpoints your scripts will hit for catalogue + config data. None of these mutate; some are cacheable for hours on your side.

Support

Spotted a missing endpoint or unclear field? We'd rather hear about it - drop a note via our feedback form.