OpenTheta API reference (1.0.0)

Download OpenAPI specification:Download

Opentheta : [email protected] URL: https://opentheta.io/

Introduction

Welcome to the API for the API for the Theta blockchain run by OpenTheta. We provide an open API to query all kind of information from the Theta network. Here are a few links:

Get help in the OpenTheta Discord channel
Follow OpenTheta on to receive announcements Twitter

Rate limiting

All requests are rate limited to ensure the API remains responsive for everyone. Only make one request at a time and not more than one request per second. If you receive a response with a 429 status, wait a full minute before resuming.

User Agent / Identification

When using this API make sure you are providing a User Agent header that contains information on your application and how we can contact you. In case we detect abnormal or suspicious activity, we will then try to contact you. If you do not supply the necessary information, we may block your application entirely.

A good example for the User Agent is: MyProjectWebsite.tld ([email protected])

Endpoints

Information about the OpenTheta marketplace, listed collections, smart contracts and NFTs on the Theta blockchain.

Get recent events

Returns the most recent events on OpenTheta. Event types can be used to filter by the type of event. The following table explains each event and the associated properties.

Event Type	Description	From	To	Value
trade	NFT was traded/sold	Seller	Buyer	Sale price
trade_usd	NFT was traded/sold (in USD on ThetaDrop)	Seller	Buyer	Sale price
list	NFT was listed for sale	Owner	`null`	Sale price
delist	NFT was delisted	Owner	`null`	Sale price
mint	NFT was minted	`0x000..`	Owner	Mint price
transfer	NFT was transferred (but not minted/burned)	Old owner	New owner	-
burn	NFT was burned	Old owner	`0x000..`	-
price_update	NFT price (on OpenTheta) was updated	Owner	`null`	New sale price

query Parameters

eventType	Array of strings (EventType) Items Enum: "trade" "list" "delist" "mint" "transfer" "burn" "price_update" Example: eventType=mint,transfer,trade Limit the events to a specific type of event or multiple event types. You can also pass multiple event types by separating them with a comma. The order of the event types does not matter.
contractAddress	string Example: contractAddress=0xe45610E578d4eb626121f55A61aB346A619B7d99 Optional address of the contract to limit it to that specific smart contract. Otherwise the events of all collections are returned.
tokenId	string Example: tokenId=123 Limit events to a specific tokenId. Requires the contract_address to be set.
ownerAddress	string Example: ownerAddress=0x19819fe24fdfe268f372138f6e8010bef6911ef6 Limit events to a single address meaing that address will always appear in either `fromAddress` or `toAddress`.
market	string Value: "opentheta" Limit events to a specific market. Currently you can only limit events to "opentheta". Otherwise all events from all marketplaces on the blockchain will be returned.
year	integer >= 2021 Limit events to a specific year.
limit	integer [ 1 .. 100 ] The number of events to retrieve. Defaults to `20`.
cursor	string A cursor pointing to the page to retrieve.

Responses

Response Schema: application/json

	Array of objects (Event)
next	string or null
previous	string or null

Response samples

Content type

application/json

{"events": [{"id": 0,
"type": "trade",
"contractAddress": "0xe45610e578d4eb626121f55a61ab346a619b7d99",
"tokenId": "395",
"fromAddress": "0xb3324c44fe6feee11d41835cbd601869a31d0cda",
"toAddress": "0x5912ce3a1425e7dc5454793a91bb48d6038647e9",
"valueTfuel": 1234.56,
"tx": {"timestamp": 1660832980,
"hash": "0x3791c7723404e1024f9bbc7e6879ab8ca640c402528299b37f4faf66cb4cdae8",
"block": 16710398
},
"asset": {"url": "https://opentheta.io/nft/0xe45610e578d4eb626121f55a61ab346a619b7d99/395",
"tokenURI": "https://ipfs.io/ipfs/QmaTssCFkteWfSGdKJuobzPDT3EDGGpEqqxBUb7HEVcvAM/7430",
"name": "ThetaMillion.com #539: 20x20 at (740,800)",
"image": "https://arweave.net/MOdyLGjXa0y9exPXTHOhk98qRxi0LqMOEeJ0myYadCk",
"animation_url": null
},
"collection": {"name": "ThetaMillion",
"url": "https://opentheta.io/collection/thetamillion",
"image": "https://images.opentheta.io/projects/0xe45610e578d4eb626121f55a61ab346a619b7d99.jpg"
},
"creator": {"name": "ThomasOnTheta",
"image": "https://images.opentheta.io/creators/thomasontheta.jpg"
}
}
],
"next": "nADIgOg",
"previous": null
}

Get collections

This endpoint provides a list of all the collections supported by OpenTheta.

Responses

Response Schema: application/json

Array of objects (Collection)

Response samples

Content type

application/json

{"collections": [{"id": 0,
"contractAddress": "0xe45610e578d4eb626121f55a61ab346a619b7d99",
"name": "ThetaMillion",
"url": "https://opentheta.io/collection/thetamillion",
"image": "https://images.opentheta.io/projects/0xe45610e578d4eb626121f55a61ab346a619b7d99.jpg",
"totalSupply": 900,
"totalSupplyWithBurned": 950,
"maxSupply": 1000,
"market": {"supply": 150,
"launchTimestamp": 1660832980,
"volume30d": 1234,
"priceTfuel": {"avg": 123.45,
"high": 123456.7,
"low": 12.34
}
},
"mint": {"mintable": true,
"mintableSoon": false,
"startTimestamp": 1660832980,
"endTimestamp": 1660882980
},
"creator": {"name": "ThomasOnTheta",
"image": "https://images.opentheta.io/creators/thomasontheta.jpg"
}
}
]
}

Get NFTs

Returns the items of a contract, collection or owner.

query Parameters

contractAddress	string Example: contractAddress=0x1f3de9cdb1d4ed10e8b7b3f21f282d84f7f54473 Get items of the contract.
collection	string Example: collection=thetapunks Get items of a collection. Value must be a OpenTheta collection key.
ownerAddress	string Example: ownerAddress=0x19819fe24fdfe268f372138f6e8010bef6911ef6 Get items owned by a specific address.
name	string Example: name=Custom Only matches items that contain the given keyword in their NFT name.
status	string Enum: "all" "for-sale" "auction" "owned" Limit items to a specific status, all items; only for sale, only items being auctioned or only items being owned (e.g. by a specific user).
priceMin	integer Only matches items with the given minimal price.
priceMax	integer Only matches items with the given maximal price.
rankMin	integer In case, stats are activated, only matches items with the given minimal rank.
rankMax	integer In case, stats are activated, only matches items with the given maximal rank.
sort	string Enum: "lowest-price" "highest-price" "name" "recent-transfer" "token-id-lowest" "token-id-highest" "rarity" "rarity-lowest" Order of items. Defaults to `lowest-price`.
limit	integer Number of items to return. Defaults to `50`.
page	integer Page of items to return (respecting the given limit).

Responses

Response Schema: application/json

Array of objects (NftItem)

Response samples

Content type

application/json

{"items": [{"id": 12345,
"contractAddress": "0x1f3de9cdb1d4ed10e8b7b3f21f282d84f7f54473",
"tokenId": "2886",
"name": "ThetaPunk #6335",
"imageUrl": "https://arweave.net/Rl1pWd4KHNoktoF_M5QkVnlJyeX7aJGdP49G3zMMee0",
"listedPrice": 500,
"rank": 10
}
]
}

Get attributes by users

This endpoint provides a list of all attributes and owners of NFTs of a contract.

path Parameters

contractAddress

string

Example: 0xe45610E578d4eb626121f55A61aB346A619B7d99

Address of the contract.

Responses

Response Schema: application/json

isListed	boolean Whether this contract is listed on OpenTheta. Attribute information is only provided for OpenTheta contracts.
attributes	object List of available attributes. See example.
	Array of objects List of owners ordered by most owned tokens.

Response samples

Content type

application/json

{"isListed": true,
"attributes": {"Color": {"items": ["Red",
"Green",
"Blue"
],
"type": "string"
}
},
"owners": [{"address": "0x5380cf25f3cf4004c8e62db0f13fce798beef278",
"ownedAmount": 3,
"attributes": {"Color": ["Red",
"Green",
"Green"
]
}
},
{"address": "0x19819fe24fdfe268f372138f6e8010bef6911ef6",
"ownedAmount": 2,
"attributes": {"Color": ["Green",
"Blue"
]
}
}
]
}

Get all NFT owners

This endpoint provides a list of all owners of all tokens of a contract.

path Parameters

contractAddress

string

Example: 0xe45610E578d4eb626121f55A61aB346A619B7d99

Address of the contract.

Responses

Response Schema: application/json

object

Map of tokenId to owner address

Response samples

Content type

application/json

{"owners": {"0": "0x1c7c0262f77c088073f89f00a92dbf056b260e2f",
"1": "0xd52bbebce2052f77c0fda982ea7071f9326cc005",
"2": "0xe54db11d8c462b0e5d59836359301c2b60f2dfad"
}
}

Get top NFT owners

This endpoint provides a list of owners with the most NFTs of a contract and the number of held NFTs.

path Parameters

contractAddress

string

Example: 0xe45610E578d4eb626121f55A61aB346A619B7d99

Address of the contract.

query Parameters

limit

integer [ 1 .. 1000 ]

The number of owners to retrieve. Defaults to 100.

Responses

Response Schema: application/json

Array of objects

Response samples

Content type

application/json

{"topOwners": [{"ownedAmount": 30,
"ownerAddress": "0x5380cf25f3cf4004c8e62db0f13fce798beef278"
},
{"ownedAmount": 29,
"ownerAddress": "0xf2976c06382b2f9538b2f40fcdf0bb21eac53ca7"
},
{"ownedAmount": 19,
"ownerAddress": "0x6b0090670f2fc7b2365c06733b353ee0f7041788"
},
{"ownedAmount": 19,
"ownerAddress": "0xc569ca7af0b81aa9ab66397c4d97a0ed6f3a1f50"
},
{"ownedAmount": 17,
"ownerAddress": "0x5351ae6a878266eb7c5d8c5dcca43eb4c35cfe86"
}
]
}