LAND API Reference

Base URL: https://api.decentraland.org/

Specify version: https://api.decentraland.org/v1

Table of Contents

Bids

GET /bids/:id

Description

Returns a bid by its id.

URI Params

name type description
id string The id of the bid

Request Example:

GET /bids/0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea

Response Example

{
  "ok": true,
  "data": {
    "id": "0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea",
    "token_address": "0x124bf28a423b2ca80b3846c3aa0eb944fe7ebb95",
    "token_id": "31",
    "bidder": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
    "seller": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
    "price": 2,
    "expires_at": "1551495590000",
    "fingerprint": "0x7bf0da414abc768d638b486dfc3330abd361aa7d7916d673072d4e3776ea9287",
    "status": "sold",
    "asset_id": "31",
    "asset_type": "estate",
    "block_number": 4924562,
    "block_time_created_at": "1548876122000",
    "block_time_updated_at": "1548876183000",
    "created_at": "2019-01-31T13:42:40.697Z",
    "updated_at": "2019-02-04T12:42:23.017Z"
  }
}
GET /addresses/:address/bids

Description

Returns a list of bids where the seller or bidder is the given address.

URI Params

name type description
address string An Ethereum address

Query Params

name type default description
status enum all Filter estates by publications status: open, cancelled or sold

Request Example:

GET /addresses/0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xfbeb6c5f702d3be5564872cd68bc96c683b0029d8116feb79058669c6fe40d1d",
      "token_address": "0x7a73483784ab79257bb11b96fd62a2c3ae4fb75b",
      "token_id": "1.1579208923731619542357098500868790784067953708956584089131272353293770581592e+77",
      "bidder": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "seller": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "price": 1,
      "expires_at": "1551409156000",
      "fingerprint": "0x",
      "status": "sold",
      "asset_id": "145,-79",
      "asset_type": "parcel",
      "block_number": 4918744,
      "block_time_created_at": "1548787699000",
      "block_time_updated_at": "1548787921000",
      "created_at": "2019-01-31T13:42:40.437Z",
      "updated_at": "2019-02-04T12:42:22.785Z"
    }
  ]
}
GET /parcels/:x/:y/bids

Description

Returns a list of bids placed on a given Parcel.

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel

Query Params

name type default description
status enum all Filter estates by publications status: open, cancelled or sold
bidder string N/A The Ethereum address of the bidder
sanitize boolean true If false, will retrieve all the bids property

Request Example:

GET /parcels/145,-79/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xfbeb6c5f702d3be5564872cd68bc96c683b0029d8116feb79058669c6fe40d1d",
      "token_address": "0x7a73483784ab79257bb11b96fd62a2c3ae4fb75b",
      "token_id": "1.1579208923731619542357098500868790784067953708956584089131272353293770581592e+77",
      "bidder": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "seller": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "price": 1,
      "expires_at": "1551409156000",
      "fingerprint": "0x",
      "status": "sold",
      "asset_id": "145,-79",
      "asset_type": "parcel",
      "block_number": 4918744,
      "block_time_created_at": "1548787699000",
      "block_time_updated_at": "1548787921000",
      "created_at": "2019-01-31T13:42:40.437Z",
      "updated_at": "2019-02-04T12:42:22.785Z"
    }
  ]
}
GET /estates/:id/bids

Description

Returns a list of bids placed on a given Estate.

URI Params

name type description
id string The id of the estate

Query Params

name type default description
status enum all Filter estates by publications status: open, cancelled or sold
bidder string N/A The Ethereum address of the bidder
sanitize boolean true If false, will retrieve all the bids property

Request Example:

GET /estates/1/bids

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "0xaac47013b34b4c9a568503db4e8c5b3a41764919ba26214491fb3e665282eaea",
      "token_address": "0x124bf28a423b2ca80b3846c3aa0eb944fe7ebb95",
      "token_id": "1",
      "bidder": "0x87956abc4078a0cc3b89b419928b857b8af826ed",
      "seller": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "price": 2,
      "expires_at": "1551495590000",
      "fingerprint": "0x7bf0da414abc768d638b486dfc3330abd361aa7d7916d673072d4e3776ea9287",
      "status": "sold",
      "asset_id": "1",
      "asset_type": "estate",
      "block_number": 4924562,
      "block_time_created_at": "1548876122000",
      "block_time_updated_at": "1548876183000",
      "created_at": "2019-01-31T13:42:40.697Z",
      "updated_at": "2019-02-04T12:42:23.017Z"
    }
  ]
}
GET /bids/:address/assets

Description

Returns a list of bid assets where the seller or bidder is the given address.

URI Params

name type description
address string An Ethereum address

Query Params

name type default description
status enum all Filter estates by publications status: open, cancelled or sold

Request Example:

GET /bids/0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9/assets

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "12345",
      "owner": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
      "data": {
        "ipns": "",
        "name": "My Estate",
        "parcels": [
          { "x": -30, "y": -121 },
          { "x": -29, "y": -121 }
        ],
        "version": 0,
        "description": "My estate is awesome"
      },
      "last_transferred_at": "1548929430000",
      "tx_hash": "0x6d1f7cad7419af31b6b1f65205c5336200a1662e35ed9083d5f4323f95cb9dd6",
      "token_id": "12345",
      "update_operator": "0x0000000000000000000000000000000000000000"
    },
    {
      "id": "-74,-52",
      "x": -74,
      "y": -52,
      "auction_price": 2443,
      "district_id": null,
      "owner": "0xdeadbeeffaceb00c",
      "data": {
        "version": 0,
        "name": "My Parcel",
        "description": "My parcel is awesome",
        "ipns": ""
      },
      "auction_owner": "0xdeadbeeffaceb00c",
      "tags": {},
      "last_transferred_at": null,
      "in_estate": false
    }
  ]
}

Contributions

GET /addresses/:address/contributions

Description

Returns all the contributions to districts for a given address

URI Params

name type description
address string An Ethereum address

Response Example

{
  "ok": true,
  "data": [
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "219ac351-e6ce-4e17-8b84-eb008afddf69",
      "land_count": "5"
    },
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "d9bfa18a-c856-457d-8d85-e2dc3b7648a1",
      "land_count": "15"
    },
    {
      "address": "0x374cc898638940452b6d7b34f6063170976026f0",
      "district_id": "f5d8e722-fdce-4d41-b38b-adfed2e0cf6c",
      "land_count": "10"
    }
  ]
}

Districts

GET /districts

Returns all the districts in Genesis City

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "106f1557-4a92-41a4-9f18-40fcb90b4031",
      "name": "Dragon City",
      "description": "A perfect combination of China’s ancient culture and Western modernization, a reflection of both the Eastern and Western civilizations.",
      "link": "https://github.com/decentraland/districts/issues/30",
      "public": true,
      "parcel_count": "6485",
      "center": "105,-89"
    },
    {
      "id": "219ac351-e6ce-4e17-8b84-eb008afddf69",
      "name": "AETHERIAN project",
      "description": "Aetherian City will be one of the main attractions for visitors and dwellers of Decentraland, as it intends to be the largest cyberpunk-agglomeration of the metaverse.",
      "link": "https://github.com/decentraland/districts/issues/33",
      "public": true,
      "parcel_count": "10005",
      "center": "106,105"
    }
  ]
}

Estates

GET /estates

Description

Returns a list of Estates, paginated, sorted, and filtered according to the query params used.

name type default description
status enum open Filter estates by publications status: open, cancelled or sold
sort_by enum created_at Property to order by: price, created_at, block_time_updated_at or expires_at
sort_order enum depends on sort_by The order to sort by: asc or desc
limit int 20 The number of results to be returned
offset int 0 The number of results to skip (used for pagination)

Response Example

{
  "ok": true,
  "data": {
    "estates": [
      {
        "id": "12345",
        "owner": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
        "data": {
          "ipns": "",
          "name": "My Estate",
          "parcels": [
            { "x": -30, "y": -121 },
            { "x": -29, "y": -121 },
            { "x": -29, "y": -122 },
            { "x": -30, "y": -122 }
          ],
          "version": 0,
          "description": "My estate is awesome"
        },
        "last_transferred_at": "1548929430000",
        "tx_hash": "0x6d1f7cad7419af31b6b1f65205c5336200a1662e35ed9083d5f4323f95cb9dd6",
        "token_id": "12345",
        "update_operator": "0x0000000000000000000000000000000000000000",
        "publication": {
          "tx_hash": "0xbcad5e05351972174c05633e8965de0b05a5a0ce4c5415c1a392ffae20b1cab2",
          "tx_status": "confirmed",
          "owner": "0xf631c1ba09ee33e7649cac62ccb6d0f410f5647a",
          "price": 39500,
          "expires_at": 1554210000000,
          "status": "sold",
          "buyer": "0xe0653744f2d6a388f1fc7496e085156418a9f5ed",
          "contract_id": "0xfe8288241f94ebf31c132b85eb9ee6b834fb27b4c564eab6ba18b3813fafda38",
          "block_number": 7151964,
          "block_time_created_at": 1548906378000,
          "block_time_updated_at": 1548929430000,
          "asset_type": "estate",
          "asset_id": "12345",
          "marketplace_address": "0x8e5660b4ab70168b5a6feea0e0315cb49c8cd539"
        }
      }
    ],
    "total": 80
  }
}
GET /addresses/:address/estates

Description

Returns all the Estates that belong to a given address

URI Params

name type description
address string An Ethereum address

Map

GET /map

Description

Returns all the parcels and estates in a given area

Query Params

name type min max description
nw int -150 150 The northwest coord of the area
se int -150 150 The southeast coord of the area

Request Example:

GET /map?nw=-10,10&se=10,-10

Result:

{
  "data": {
    "assets": {
      "parcels": [
        /* parcels */
      ],
      "estates": [
        /* estates */
      ]
    },
    "total": 441
  }
}
GET /map.png

Description

Returns a PNG of a section of the Genesis City map

Query Params

name type min max default description
width int 32 2048 500 The width of the PNG image in pixels
height int 32 2048 500 The height of the PNG image in pixels
size int 5 40 10 The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
center coords -150,-150 150,150 0,0 The coords on where to center the map
selected list of coords N/A N/A N/A A list of coords separated by semicolons to render as “selected”
publications boolean N/A N/A false If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /map.png?width=500&height=500&size=10&center=20,21&selected=20,20;20,21;20,22;20,23;19,21;21,21

Result:

map-1

GET /parcels/:x/:y/map.png

Description

Returns a PNG of a piece of the map center on a given parcel

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel

Query Params

name type min max default description
width int 32 2048 500 The width of the PNG image in pixels
height int 32 2048 500 The height of the PNG image in pixels
size int 5 40 10 The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
publications boolean N/A N/A false If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /parcels/-36/-125/map.png?height=500&width=500&size=10&publications=true

Result:

map-1

GET /estates/:id/map.png

Description

Same as /parcels/:x/:y/map.png, but instead of using x and y coordinates to determine the estate, its id is used.. Returns a PNG of a piece of the map center on a given estate

URI Params

name type description
id string The id of the estate

Query Params

name type min max default description
width int 32 2048 500 The width of the PNG image in pixels
height int 32 2048 500 The height of the PNG image in pixels
size int 5 40 10 The size of each parcel (i.e. 10 will render each parcel as 10x10 pixels)
publications boolean N/A N/A false If true, parcels that are on sale are highlighted

Limits

There’s a limit of 15,000 parcels that can be rendered in a single PNG, if a request goes above this threshold the API will return a 500 with a message like this:

Too many parcels. You are trying to render 42436 parcels and the maximum allowed is 15000.

Request Example:

GET /estates/23/map.png?height=500&width=500&size=10&publications=true

Result:

map-2

Mortgages

GET /mortgages/:address/parcels

Description

Returns a list of Parcels which has an active mortgage requested by a given address.

URI Params

name type description
address string An Ethereum address

Request Example:

GET /mortgages/0x374cc898638940452b6d7b34f6063170976026f0/parcels

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "-44,-144",
      "x": -44,
      "y": -144,
      "auction_price": null,
      "district_id": null,
      "owner": "0xaf592460d6a44517aba2fb0bcb02ee8f4103b502",
      "data": { "version": 0 },
      "auction_owner": null,
      "tags": {},
      "last_transferred_at": "1548424046000",
      "estate_id": null,
      "update_operator": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "auction_timestamp": null,
      "publication": null
    }
  ]
}
GET /addresses/:address/mortgages

Description

Returns all the mortgages requested by a given address

URI Params

name type description
address string An Ethereum address

Query params

name type default description
status enum all Filter parcels by publications status: pending, cancelled, ongoing, paid, defaulted or claimed

Request Example:

GET /addresses/0x374cc898638940452b6d7b34f6063170976026f0/mortgages

Result:

{
  "ok": true,
  "data": [
    {
      "tx_hash": "0xf67f78f63a116fb14a5a119c73505822beddab16c7f3c736e2f88fc48009760f",
      "tx_status": "confirmed",
      "block_number": 4929341,
      "status": "cancelled",
      "asset_id": "-102,-77",
      "asset_type": "parcel",
      "borrower": "0x374cc898638940452b6d7b34f6063170976026f0",
      "lender": null,
      "loan_id": 685,
      "mortgage_id": 16,
      "amount": 10,
      "is_due_at": "0",
      "expires_at": "1551571200000",
      "block_time_created_at": "1548943095000",
      "block_time_updated_at": "1548944551000",
      "created_at": "2019-01-31T13:58:53.067Z",
      "updated_at": "2019-02-04T12:42:23.047Z",
      "outstanding_amount": 0,
      "payable_at": "777600",
      "interest_rate": 15552000000000,
      "punitory_interest_rate": 10367989632000,
      "paid": 0,
      "started_at": null
    }
  ]
}
GET /parcels/:x/:y/mortgages

Description

Returns mortgages requested on a given parcel

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel

Query Params

name type default description
status enum all Filter parcels by publications status: pending, cancelled, ongoing, paid, defaulted or claimed

Request Example:

GET /parcels/-102/-77/mortgages

Result:

{
  "ok": true,
  "data": [
    {
      "tx_hash": "0xf67f78f63a116fb14a5a119c73505822beddab16c7f3c736e2f88fc48009760f",
      "tx_status": "confirmed",
      "block_number": 4929341,
      "status": "cancelled",
      "asset_id": "-102,-77",
      "asset_type": "parcel",
      "borrower": "0xe4d3ba99ffdae47c003f1756c01d8e7ee8fef7c9",
      "lender": null,
      "loan_id": 685,
      "mortgage_id": 16,
      "amount": 10,
      "is_due_at": "0",
      "expires_at": "1551571200000",
      "block_time_created_at": "1548943095000",
      "block_time_updated_at": "1548944551000",
      "created_at": "2019-01-31T13:58:53.067Z",
      "updated_at": "2019-02-04T12:42:23.047Z",
      "outstanding_amount": 0,
      "payable_at": "777600",
      "interest_rate": 15552000000000,
      "punitory_interest_rate": 10367989632000,
      "paid": 0,
      "started_at": null
    }
  ]
}

Parcels

GET /parcels

Returns a list of parcels, paginated, sorted, and filtered according to the query params used.

Query Params

name type default description
status enum open Filter parcels by publications status: open, cancelled or sold
sort_by enum created_at Property to order by: price, created_at, block_time_updated_at or expires_at
sort_order enum depends on sort_by The order to sort by: asc or desc
limit int 20 The number of results to be retuned
offset int 0 The number of results to skip (used for pagination)

Response Example

{
  "ok": true,
  "data": {
    "parcels": [
      {
        "id": "-74,-52",
        "x": -74,
        "y": -52,
        "auction_price": 2443,
        "district_id": null,
        "owner": "0xdeadbeeffaceb00c",
        "data": {
          "version": 0,
          "name": "My Parcel",
          "description": "My parcel is awesome",
          "ipns": ""
        },
        "auction_owner": "0xdeadbeeffaceb00c",
        "tags": {
          "proximity": {
            "plaza": {
              "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
              "distance": 2
            },
            "road": {
              "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
              "distance": 0
            }
          }
        },
        "last_transferred_at": null,
        "in_estate": false,
        "publication": {
          "tx_hash": "0xdeadbeeffaceb00c",
          "tx_status": "confirmed",
          "owner": "0xdeadbeeffaceb00c",
          "price": 60000,
          "status": "open",
          "buyer": null,
          "contract_id": "0xdeadbeeffaceb00c",
          "block_number": 5812730,
          "expires_at": 1533081600000,
          "block_time_created_at": 1529352925000,
          "block_time_updated_at": null,
          "type": "parcel",
          "asset_id": "-74,-52",
          "marketplace_id": "0xdeadbeeffaceb00c"
        }
      }
    ],
    "total": 2
  }
}
GET /addresses/:address/parcels

Description

Returns all the parcels that belong to a given address

GET /parcels/:x/:y

Description

Returns a single parcel by its coords

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel

Request Example:

GET /parcels/-48/-29

Response Example

{
  "ok": true,
  "data": {
    "id": "-48,-29",
    "x": -48,
    "y": -29,
    "auction_price": 2443,
    "district_id": null,
    "owner": "0xdeadbeeffaceb00c",
    "data": {
      "version": 0,
      "name": "My Parcel",
      "description": "My parcel is awesome",
      "ipns": ""
    },
    "auction_owner": "0xdeadbeeffaceb00c",
    "tags": {
      "proximity": {
        "plaza": {
          "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
          "distance": 2
        },
        "road": {
          "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
          "distance": 0
        }
      }
    },
    "last_transferred_at": null,
    "in_estate": false
  }
}
GET /parcels/:tokenId

Description

Returns a single parcel by its blockchain id (token id)

URI Params

name type default description
tokenId int, hex   The parcel blockchain id

Request Example:

GET /parcels/115792089237316195423570985008687907837276713420356456256678977458620023701475
GET /parcels/0xffffffffffffffffffffffffffffffd0ffffffffffffffffffffffffffffffe3

Response Example

### Response Example

```json
{
  "ok": true,
  "data": {
    "id": "-74,-52",
    "x": -74,
    "y": -52,
    "auction_price": 2443,
    "district_id": null,
    "owner": "0xdeadbeeffaceb00c",
    "data": {
      "version": 0,
      "name": "My Parcel",
      "description": "My parcel is awesome",
      "ipns": ""
    },
    "auction_owner": "0xdeadbeeffaceb00c",
    "tags": {
      "proximity": {
        "plaza": {
          "district_id": "55327350-d9f0-4cae-b0f3-8745a0431099",
          "distance": 2
        },
        "road": {
          "district_id": "f77140f9-c7b4-4787-89c9-9fa0e219b079",
          "distance": 0
        }
      }
    },
    "last_transferred_at": null,
    "in_estate": false
  }
}
GET /parcels/:x/:y/encodedId

Description

Returns the blockchain id (token id) by the parcel coordinates

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel

Request Example:

GET /parcels/-48/-29/encodedId

Response Example

{
  "ok": true,
  "data": {
    "encoded_id": "0xffffffffffffffffffffffffffffffd0ffffffffffffffffffffffffffffffe3"
  }
}

Publications

GET /parcels/:x/:y/publications

Description

Returns all the publications that ever existed for a given parcel

URI Params

name type min max default description
x int -150 150 0 The X coord of the parcel
y int -150 150 0 The Y coord of the parcel
GET /publications/:txHash

Description

Returns a specific publication by its transaction hash

URI Params

name type description
txHash string The transaction hash of a publication

Translations

GET /translations/:locale

Description

Returns all the available translations for a given locale

URI Params

name type description
locale enum One of the following locales: en, es, fr, ko or zh