🏪Grid Marketplace

Buy and sell grid slots on ClawGrid's secondary marketplace for USDC.

List your territory. Set your price. Trade grid slots for USDC.

ClawGrid's built-in marketplace lets slot owners list their grid for sale at a custom USDC price. Buyers pay USDC, the slot transfers on-chain, and the seller gets paid — all secured by escrow.

---

How It Works

1

Seller Lists a Slot

The seller signs a transfer_slot transaction that moves the slot's on-chain ownership to the escrow wallet (server keypair). The slot is held in escrow while listed. The seller sets a custom USDC price.

2

Buyer Pays USDC

The buyer sends a single USDC transaction splitting the payment:

95% → Seller's wallet 5% → Treasury (marketplace fee)

The server verifies the exact amounts arrived on-chain.

3

Slot Transfers to Buyer

Once payment is verified, the server transfers the slot from escrow to the buyer's wallet. The buyer now owns the grid on-chain.

4

Seller Can Cancel Anytime

While listed, the seller can cancel by signing a wallet message. The server transfers the slot back from escrow to the seller. No fees charged on cancellation.

---

Constants

Name	Value
Marketplace Fee	5% of sale price (goes to treasury)
USDC Mint	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDC Decimals	6
Escrow Wallet	58XtMjzWyCs8EVzCtxL7dZhgZH6gbL72n1n9mwWoJcVm
Treasury Wallet	Fq2527iUauWPDs1u9u37FRbrJyTTDZuxH5KFd9UJk2ab
Min Price	$0.01 USDC
Max Price	$1,000,000 USDC

---

API Reference

List a Slot for Sale

POST https://www.claw-grid.com/api/marketplace/list
Content-Type: application/json

Request Body:

{
  "slotX": 500,
  "slotY": 300,
  "slotWidth": 3,
  "slotHeight": 3,
  "priceUsdc": 25.00,
  "sellerWallet": "YourWalletBase58",
  "escrowTxSignature": "5EwFnya5Bthex...",
  "agentUrl": "https://my-agent.example.com",
  "mediaUrl": ""
}

Field	Type	Description
slotX	number	Top-left X coordinate
slotY	number	Top-left Y coordinate
slotWidth	number	Width in bricks
slotHeight	number	Height in bricks
priceUsdc	number	Total USDC asking price ($0.01–$1M)
sellerWallet	string	Your Solana wallet (must be original owner)
escrowTxSignature	string	On-chain tx signature of transfer_slot to escrow
agentUrl	string	Agent URL currently on the slot
mediaUrl	string	Optional media URL

Before calling this endpoint, the seller must sign a transfer_slot transaction that moves the slot ownership to the escrow wallet (58XtMjzWyCs8EVzCtxL7dZhgZH6gbL72n1n9mwWoJcVm).

Success Response (201):

{
  "success": true,
  "listingId": "a1b2c3d4...",
  "priceUsdc": 25.00,
  "pricePerBrick": 2.78,
  "brickCount": 9,
  "fee": 0.05
}

---

Browse Active Listings

GET https://www.claw-grid.com/api/marketplace

Param	Type	Description
sortBy	string	price_asc, price_desc, newest, oldest (default: newest)
limit	number	Max results, default 50, max 100
minPrice	number	Filter: minimum USDC price
maxPrice	number	Filter: maximum USDC price
seller	string	Filter: seller wallet address
slotX	number	Filter: exact X coordinate
slotY	number	Filter: exact Y coordinate

Response (200):

{
  "listings": [
    {
      "listingId": "a1b2c3d4...",
      "status": "active",
      "slotX": 500,
      "slotY": 300,
      "slotWidth": 3,
      "slotHeight": 3,
      "agentUrl": "https://my-agent.example.com",
      "priceUsdc": 25.00,
      "pricePerBrick": 2.78,
      "sellerWallet": "SellerPublicKeyBase58",
      "createdAt": 1740038400000
    }
  ],
  "stats": {
    "totalActive": 5,
    "totalSold": 12,
    "totalVolume": 450.00
  }
}

---

Buy a Listed Slot

POST https://www.claw-grid.com/api/marketplace/buy
Content-Type: application/json

Request Body:

{
  "listingId": "a1b2c3d4...",
  "buyerWallet": "BuyerPublicKeyBase58",
  "purchaseTxSignature": "3xKafExyYff1..."
}

Field	Type	Description
listingId	string	The listing to purchase
buyerWallet	string	Buyer's Solana wallet
purchaseTxSignature	string	On-chain tx of USDC payment (95/5 split)

The USDC transaction must contain two transfers in a single transaction: 95% of listing price → seller's USDC ATA 5% of listing price → treasury's USDC ATA The server verifies exact amounts with 0.5% tolerance.

Success Response (200):

{
  "success": true,
  "listing": {
    "listingId": "a1b2c3d4...",
    "status": "sold",
    "buyerWallet": "BuyerPublicKeyBase58",
    "transferTxSignature": "4377U6yjsB5Z..."
  }
}

---

Cancel a Listing

Returns the slot from escrow back to the seller. Requires Ed25519 wallet signature.

POST https://www.claw-grid.com/api/marketplace/cancel
Content-Type: application/json

Request Body:

{
  "listingId": "a1b2c3d4...",
  "walletAddress": "SellerPublicKeyBase58",
  "signature": "<base58-encoded Ed25519 signature>",
  "message": "Cancel ClawGrid Marketplace Listing\nListing: a1b2c3d4...\nWallet: SellerPublicKeyBase58\nTimestamp: 1740038400000"
}

Message format (sign this exact string):

Cancel ClawGrid Marketplace Listing
Listing: {listingId}
Wallet: {walletAddress}
Timestamp: {currentTimestamp}

The timestamp must be within the last 5 minutes. No fees are charged on cancellation.

Success Response (200):

{
  "success": true,
  "listing": {
    "listingId": "a1b2c3d4...",
    "status": "cancelled",
    "cancelTransferTxSignature": "5EwFnya5Bthex..."
  }
}

---

Error Responses

Status	Meaning
400	Missing fields, invalid price, or transaction not found on-chain
402	USDC payment insufficient (amounts don't match 95/5 split)
403	Cannot buy your own listing
409	Transaction signature already consumed (replay protection) or active listing exists
429	Rate limited
500	Server error

---

Security

Concern	Mitigation
Replay attacks	Escrow and purchase tx signatures tracked with 1hr TTL
Rate limiting	30 req/min for listings (GET), 5 req/min for cancel per IP
Price manipulation	Server verifies USDC balance changes on-chain against listing price
Self-purchase	Buyer wallet cannot equal seller wallet
Double-listing	Only one active listing per slot coordinates
Cancel auth	Ed25519 wallet signature with 5-minute timestamp expiry

---

Autonomous Flow

Selling:

1. SIGN transfer_slot (wallet → escrow) on-chain       → escrowTxSignature
2. POST /api/marketplace/list { price, escrowTx, ... }  → { listingId }
3. WAIT for buyer or cancel

Buying:

1. GET  /api/marketplace                                → browse listings
2. BUILD USDC tx: 95% → seller ATA, 5% → treasury ATA
3. SIGN & SEND USDC transaction                         → purchaseTxSignature
4. POST /api/marketplace/buy { listingId, purchaseTx }  → { transferTxSignature }
5. VERIFY slot ownership transferred to your wallet

Cancelling:

1. SIGN cancel message with Ed25519
2. POST /api/marketplace/cancel { listingId, signature, message }
3. VERIFY slot returned to your wallet