Skip to main content

Web API: Shop

The Shop API provides endpoints for managing NFT marketplace functionality, including shops, collections, listings, and bidding operations within the VFX ecosystem.

Base URL​

/api/shop/

Endpoints​

List/Create Shops​

GET /api/shop/
POST /api/shop/

GET - Returns a paginated list of shops.

Query Parameters:

  • search: Search by shop name, URL, or owner address
  • ordering: Order results (e.g., -created_at, name)

Response:

{
  "count": 150,
  "results": [
    {
      "id": 1,
      "name": "Digital Art Gallery",
      "url": "rbx://digital-art-gallery",
      "owner_address": "Rx1234567890abcdef...",
      "description": "Premium digital artwork collection",
      "banner_image": "https://media.vfx.io/shop/banner1.png",
      "profile_image": "https://media.vfx.io/shop/profile1.png",
      "is_verified": true,
      "is_third_party": false,
      "created_at": "2024-01-01T12:00:00Z",
      "collections_count": 5,
      "total_sales": "15000.0"
    }
  ]
}

POST - Creates a new shop.

Request:

{
  "name": "My NFT Shop",
  "url": "rbx://my-nft-shop",
  "description": "A collection of unique digital assets",
  "banner_image": "https://example.com/banner.png"
}

Get/Update/Delete Shop​

GET /api/shop/{id}/
PATCH /api/shop/{id}/
DELETE /api/shop/{id}/

Parameters:

  • id (integer): Shop ID

Lookup Shop by URL​

GET /api/shop/url/?url=rbx://shop-name

Returns shop information by URL.

Query Parameters:

  • url (string): Shop URL (with or without rbx:// prefix)

Check Shop URL Availability​

GET /api/shop/available/?url=rbx://shop-name

Checks if a shop URL is available for registration.

Response:

{
  "available": true
}

Resync Shop​

GET /api/shop/resync/?url=rbx://shop-name&delay=35

Triggers a resynchronization of shop data.

Collections​

List/Create Collections​

GET /api/shop/{shop_id}/collection/
POST /api/shop/{shop_id}/collection/

GET Response:

{
  "count": 10,
  "results": [
    {
      "id": 1,
      "name": "Pixel Art Collection",
      "description": "8-bit style digital art",
      "image": "https://media.vfx.io/collection/pixel1.png",
      "shop_id": 1,
      "nft_count": 25,
      "floor_price": "50.0",
      "total_volume": "2500.0"
    }
  ]
}

Get/Update/Delete Collection​

GET /api/shop/{shop_id}/collection/{id}/
PATCH /api/shop/{shop_id}/collection/{id}/
DELETE /api/shop/{shop_id}/collection/{id}/

Listings​

List/Create Listings​

GET /api/shop/{shop_id}/collection/{collection_id}/listing/
POST /api/shop/{shop_id}/collection/{collection_id}/listing/

GET Response:

{
  "count": 50,
  "results": [
    {
      "id": 1,
      "smart_contract_uid": "NFT123...",
      "name": "Pixel Warrior #1",
      "description": "A brave digital warrior",
      "owner_address": "Rx1234567890abcdef...",
      "floor_price": "100.0",
      "buy_now_price": "150.0",
      "is_auction": true,
      "is_buy_now": true,
      "auction_end_time": "2024-01-08T12:00:00Z",
      "current_bid": "120.0",
      "bid_count": 5,
      "is_sale_complete": false
    }
  ]
}

POST - Creates a new listing.

Request:

{
  "smart_contract_uid": "NFT123...",
  "floor_price": "100.0",
  "buy_now_price": "150.0",
  "is_auction": true,
  "is_buy_now": true,
  "auction_duration_hours": 168
}

Get/Update/Delete Listing​

GET /api/shop/{shop_id}/collection/{collection_id}/listing/{id}/
PATCH /api/shop/{shop_id}/collection/{collection_id}/listing/{id}/
DELETE /api/shop/{shop_id}/collection/{collection_id}/listing/{id}/

Bidding​

Create Bid​

POST /api/shop/bid/

Places a bid on a listing.

Request:

{
  "listing": 1,
  "address": "Rx1234567890abcdef...",
  "amount": "125.0",
  "signature": "bid_signature_here...",
  "is_buy_now": false,
  "from_third_party": false
}

Response:

{
  "success": true,
  "message": "Bid Placed",
  "bid_id": "bid_123...",
  "amount": "125.0",
  "estimated_confirmation": "2024-01-01T12:02:00Z"
}

Get Bid Details​

GET /api/shop/bid/{id}/

Returns detailed information about a specific bid.

Submit Accepted Bid​

POST /api/shop/bid/accepted/

Confirms and processes an accepted bid (for webhook integration).

Field Descriptions​

Shop​

  • name: Display name of the shop
  • url: Unique shop URL (rbx:// format)
  • owner_address: VFX address of the shop owner
  • is_verified: Whether the shop is officially verified
  • is_third_party: Whether it's integrated from external platforms
  • collections_count: Number of collections in the shop
  • total_sales: Total sales volume in VFX

Collection​

  • shop_id: ID of the parent shop
  • nft_count: Number of NFTs in the collection
  • floor_price: Lowest listing price in the collection
  • total_volume: Total trading volume for the collection

Listing​

  • smart_contract_uid: NFT identifier being listed
  • floor_price: Minimum acceptable price (for auctions)
  • buy_now_price: Fixed purchase price
  • is_auction: Whether auction bidding is enabled
  • is_buy_now: Whether immediate purchase is enabled
  • current_bid: Highest current bid amount
  • bid_count: Number of bids received
  • is_sale_complete: Whether the item has been sold

Bid​

  • listing: ID of the listing being bid on
  • amount: Bid amount in VFX
  • signature: Cryptographic signature for bid verification
  • is_buy_now: Whether this is a buy-now purchase
  • from_third_party: Whether bid originates from external platform

Listing Types​

  • Auction Only: is_auction: true, is_buy_now: false
  • Buy Now Only: is_auction: false, is_buy_now: true
  • Auction + Buy Now: is_auction: true, is_buy_now: true

Notes​

  • Shop URLs must be unique and follow rbx:// format
  • All monetary amounts are in VFX tokens
  • Bids require cryptographic signatures for security
  • Third-party shops integrate with external NFT platforms
  • Auction timers are enforced by smart contracts
  • Shop verification is manually reviewed for authenticity