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": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
      "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": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
      "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": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
  "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