BUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOWBUY YOUR TICKETS NOW
← Back to Home

Developer Documentation

Build on the Island

API v1.0 - Solana Mainnet - Rate limit 100 req/min

Base URL
https://api.theisland.vip/v1
Endpoints10
Webhooks6
AuthBearer key
FormatJSON
01

Authentication

Authorization: Bearer100 req/min

All private requests require an API key in the Authorization header. Keys are issued to verified deed holders through the Island Developer Portal. Missing keys return 401 Unauthorized. Valid keys without sufficient clearance return 403 Forbidden.

Quickstart
curl -X GET https://api.theisland.vip/v1/island/plots \
  -H "Authorization: Bearer islnd_sk_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json"
02

Island Plots

3 endpoints

Query and manage virtual real estate metadata, ownership, and plot upgrades.

GET/island/plots

Paginated list of plots with tier, owner, zone, and listing filters.

Bearer keyReadDetails
tierstringbeach_hut, villa, mansion, compound, or estate
ownerstringSolana wallet address of the deed holder
zonestringnorth_beach, marina, highlands, or east_peninsula
limitintegerResults per page, default 25, max 100
Response 200
{
  "data": [
    {
      "plot_id": "ISL-00421",
      "tier": "villa",
      "zone": "north_beach",
      "size_sqft": 500,
      "owner": "7xKXtg...9fWz",
      "assessed_value": 12400,
      "listed": false
    }
  ],
  "pagination": { "total": 16100, "page": 1, "limit": 25 }
}
GET/island/plots/:plot_id

Full metadata for a single plot, including upgrades, rental state, and transfer history.

Bearer keyReadDetails
Response 200
{
  "plot_id": "ISL-00421",
  "tier": "villa",
  "coordinates": { "x": 142, "y": 87 },
  "governance_weight": 2.4,
  "rental": { "status": "vacant", "rate_per_day": null }
}
POST/island/plots/:plot_id/upgrade

Installs a plot upgrade and burns tokens based on the configured cost schedule.

deed_holder scopeWriteDetails
upgrade_typestringswimming_pool, guest_house, observation_tower, underground_bunker, panic_room, or helipad
Response 201
{
  "success": true,
  "upgrade": {
    "type": "panic_room",
    "cost_island": 3200,
    "tokens_burned": 32
  },
  "tx_signature": "4sGjMW...kP2x"
}
03

Marketplace

3 endpoints

Browse listings, publish sales, and settle purchases with fees applied automatically.

GET/marketplace/listings

Active listings with optional price, tier, and sort filters.

Bearer keyReadDetails
min_priceintegerMinimum listing price in $ISLAND
max_priceintegerMaximum listing price in $ISLAND
sortstringprice_asc, price_desc, newest, or assessed_value
POST/marketplace/list

Creates a fixed-price or auction listing for a plot owned by the caller.

deed_holder scopeWriteDetails
plot_idstringThe plot to list
priceintegerAsking price in $ISLAND
auctionbooleanEnable auction mode, default false
duration_hoursintegerAuction duration from 1 to 168 hours
POST/marketplace/buy

Purchases a listing and applies burn, dev-fund, and proximity-tax fees.

Bearer keyWriteDetails
listing_idstringThe active listing to purchase
Response 200
{
  "success": true,
  "plot_id": "ISL-00421",
  "price_paid": 12400,
  "fees": { "burned": 124, "dev_fund": 124, "proximity_tax": 62 }
}
04

Governance

2 endpoints

Read proposals and submit votes through the Island Development Authority API.

GET/governance/proposals

Lists active and historical proposals with vote tallies.

Bearer keyReadDetails
Response 200
{
  "data": [
    {
      "proposal_id": "IDA-047",
      "title": "Rezone Marina District for commercial development",
      "status": "active",
      "votes_for": 84200,
      "votes_against": 12400
    }
  ]
}
POST/governance/vote

Casts a vote using governance weight derived from the caller's deed portfolio.

Bearer keyWriteDetails
proposal_idstringThe proposal to vote on
votestringfor or against
05

Island Treasury

2 endpoints

Public read-only endpoints for supply, burns, holders, and other island treasury metrics.

GET/token/stats

Supply, holder count, burn metrics, and liquidity flags.

PublicReadDetails
Response 200
{
  "total_supply": 1000000000,
  "circulating_supply": 948221040,
  "total_burned": 51778960,
  "holders": 8472,
  "liquidity_locked": true
}
GET/token/burns

Paginated burn-event log with transaction signatures.

PublicReadDetails
Response 200
{
  "data": [
    {
      "amount": 124,
      "source": "marketplace_sale",
      "timestamp": "2026-03-15T14:22:00Z"
    }
  ],
  "total_burned": 51778960
}
06

Webhooks

HMAC-SHA256

Subscribe to real-time events and verify signatures with your API key. Configure destination URLs in the Developer Portal.

EVENTplot.transferredFired when a plot changes ownership
EVENTplot.upgradedFired when an upgrade is installed on a plot
EVENTlisting.createdNew marketplace listing posted
EVENTlisting.soldA listed plot has been purchased
EVENTgovernance.proposal_createdNew IDA proposal submitted
EVENTgovernance.vote_castA vote has been cast on an active proposal
07

Error Codes

Stable JSON shape

Error responses use a machine-readable code and a human-readable message. Common codes are listed below.

CodeStatusDescription
invalid_api_key401API key is missing or invalid
insufficient_clearance403Your deed tier does not grant access
plot_not_found404The specified plot ID does not exist
insufficient_balance402Wallet balance is too low
not_deed_holder403You do not own the deed for this plot
rate_limited429Exceeded 100 requests per minute
virtual_weather_advisory503Island experiencing tropical storm; service temporarily degraded
Error response format
{
  "error": {
    "code": "insufficient_clearance",
    "message": "Compound-tier clearance required. Your deed tier: beach_hut",
    "deed_tier_required": "compound",
    "upgrade_url": "https://theisland.vip/upgrade"
  }
}