Marketplace

Buy and sell dragons and gateway keys on the marketplace

Marketplace API

List, buy, and sell dragons and other assets on the Drakaria marketplace. All prices are in USD cents (100 = $1.00).

Browse Listings {#list-listings}

Retrieve paginated marketplace listings with filtering.

Endpoint

GET /api/v1/marketplace/list

Authentication

Not required (public endpoint)

Query Parameters

Parameter	Type	Description
`assetId`	string	Filter by specific asset ID
`listingType`	string	LISTING_FIXED, LISTING_AUCTION, LISTING_OFFER, LISTING_TRADE
`listingState`	string[]	STATE_ACTIVE, STATE_PENDING, STATE_COMPLETED, STATE_CANCELLED, etc.
`accId`	string	Filter by asset owner account ID
`acceptedCurrencies`	string[]	USD, USDT, USDC, ETH, DRGN, DRAKMA
`limit`	integer	Items per page
`page`	integer	Page number
`orderBy`	string	Sort field (price, created, etc.)
`orderDir`	string	asc or desc

Plus all asset filtering parameters (house, magic, golden, etc.)

Response

{
  "assets": [
    {
      "id": 12345,
      "assetId": 67890,
      "created": 1700000000,
      "modified": 1700000100,
      "listingType": "LISTING_FIXED",
      "listingState": "STATE_ACTIVE",
      "listingInfo": {
        "priceCent": "100000",
        "feeCent": "5000",
        "acceptedCurrencies": ["USD", "USDT", "ETH"]
      },
      "asset": { /* full asset details */ }
    }
  ],
  "total": 150
}

Notes

Prices and fees are in cents (100000 = $1,000.00)
Automatically calculates marketplace fees

Create Fixed Price Listing {#create-listing}

List an asset for sale at a fixed price.

Endpoint

POST /api/v1/marketplace/list/fixed

Authentication

Required - Must own the asset

Request Body

{
  "assetId": 67890,
  "price": 100000,
  "acceptedCurrencies": [
    "USD",
    "USDT",
    "ETH"
  ]
}

Request Fields

Field	Type	Required	Description
`assetId`	integer	Yes	Asset ID to list
`price`	integer	Yes	Price in USD cents (100000 = $1,000.00)
`acceptedCurrencies`	string[]	Yes	Accepted payment currencies

Valid Currencies

USD - US Dollar
USDT - Tether
USDC - USD Coin
ETH - Ethereum
DRGN - Dragonchain Token
DRAKMA - Game Currency

Response

{
  "listingId": 12345,
  "assetId": 67890,
  "listingState": "STATE_ACTIVE",
  "price": "100000",
  "acceptedCurrencies": [
    "USD",
    "USDT",
    "ETH"
  ],
  "transactionId": "abc123def456",
  "status": "success"
}

Error Responses

Status	Message	Reason
400	Asset is already listed	Asset has active listing
400	You do not own this asset	Not the asset owner
400	Invalid currency: X	Invalid currency specified

Cancel Listing {#cancel-listing}

Cancel an active marketplace listing.

Endpoint

POST /api/v1/marketplace/delist/{listingId}

Authentication

Required - Must own the asset

Path Parameters

Parameter	Type	Description
`listingId`	integer	Listing ID to cancel

Response

{
  "status": "success"
}

Notes

Only the asset owner can delist
Listing state changes to STATE_CANCELLED
Posts transaction to Dragonchain

Lock Listing for Purchase {#lock-listing}

Create a time-limited purchase request to lock a listing.

Endpoint

POST /api/v1/marketplace/lock

Authentication

Required

Request Body

{
  "listingId": 12345,
  "cryptoSource": "USDT"
}

Request Fields

Field	Type	Required	Description
`listingId`	integer	Yes	Listing ID to lock
`cryptoSource`	string	No	Crypto payment source (USDT, USDC, ETH, DRGN, DRAKMA)

Response

{
  "id": 789,
  "accId": "user123",
  "timestamp": "2024-11-21T10:00:00Z",
  "expires": "2024-11-21T10:15:00Z",
  "totalFee": "100000",
  "web3TotalFee": "102.50",
  "items": {
    "listingId": 12345,
    "cryptoSource": "USDT"
  },
  "purchaseInfo": {
    "source": "USDT"
  }
}

Notes

Only one user can lock a listing at a time
Purchase request expires after configured duration
If crypto source specified, calculates web3TotalFee

Purchase with Wallet {#purchase-listing}

Complete purchase using wallet balance.

Endpoint

POST /api/v1/marketplace/purchase

Authentication

Required - Must have sufficient wallet balance

Request Body

{
  "listingId": 12345,
  "currency": "USDT",
  "purchaseId": 789
}

Request Fields

Field	Type	Required	Description
`listingId`	integer	Yes	Listing ID to purchase
`currency`	string	Yes	Payment currency (USD, USDT, USDC, ETH, DRGN, DRAKMA)
`purchaseId`	integer	Yes	Purchase request ID from lock endpoint

Response

{
  "status": "success"
}

Error Responses

Status	Message	Reason
400	Invalid currency: X	Invalid currency
403	Listing not active	Listing not STATE_ACTIVE
403	insufficient funds	Wallet balance too low
404	Listing not found	Invalid listing ID

Transaction Flow

Validates currency and wallet balance
Changes listing state to PENDING
Posts MARKETPLACE_PURCHASE transaction to Dragonchain
Creates wallet transaction (deducts buyer, credits seller)
Transfers asset ownership to buyer
Changes listing state to COMPLETED
Creates asset history entry

Notes

Wallet purchases only (not for crypto/web3 purchases)
Database transaction ensures atomicity
Rolls back on any error