Get account
Get information about a users account on the On3 platform, including currency balances, rewards earned, quests completed, and shop items purchased.
Data is cached for performance. Account lookups by social ID are cached for 1 hour. Account data is cached for 5 minutes, while context data (balances, quests, rewards, etc.) is cached for 15 minutes. For real-time data please contact the On3 team for further details.
Use Cases
-
Create a dynamic membership card that displays the users points and XP balances in real time.
-
Reward users for completing X number of quests.
Request
HTTP GET to /accounts with Content-Type: application/json using any combination of the following query parameters: address[], email[], telegramId[], discordId[], or twitterId[]. You can fetch multiple accounts by passing any of these parameters as many times as you need.
- Example
/accounts?address=0x435Cd3902d1b4f4E842F2C0fd5028EEE71dd099C&email=paul%40on3app.com&discordId=123456789012345678
Query string parameters
address[]
Checksum'd EIP-55 compliant wallet address. You can pass a single wallet address or multiple up to the max. URL length (2048 characters).
| Type | string[] |
| Required | No (at least one lookup parameter must be provided) |
| Limitations | A string array of valid wallet addresses (0x...) |
| Examples | "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" |
email[]
E-mail address of the account to lookup. You can pass a single email address or multiple up to the max. URL length (2048 characters).
| Type | string[] |
| Required | No (at least one lookup parameter must be provided) |
| Limitations | A string array of valid urlencoded email addresses |
| Examples | "paul%40on3app.com" |
telegramId[]
Telegram user ID of the account to lookup. You can pass a single ID or multiple up to the max. URL length (2048 characters).
| Type | string[] |
| Required | No (at least one lookup parameter must be provided) |
| Limitations | A string array of valid Telegram user IDs (numeric strings) |
| Examples | "123456789" |
discordId[]
Discord user ID (snowflake) of the account to lookup. You can pass a single ID or multiple up to the max. URL length (2048 characters).
| Type | string[] |
| Required | No (at least one lookup parameter must be provided) |
| Limitations | A string array of valid Discord snowflake IDs (numeric strings) |
| Examples | "123456789012345678" |
twitterId[]
Twitter/X user ID of the account to lookup. You can pass a single ID or multiple up to the max. URL length (2048 characters).
| Type | string[] |
| Required | No (at least one lookup parameter must be provided) |
| Limitations | A string array of valid Twitter user IDs (numeric strings) |
| Examples | "123456789" |
include
What data to include in the response. The default is account,balances but you may pass any combination of:
allreturn all of the below types.accountreturn account related information such as social connections, e-mail address, username, etc.experiencereturn the users XP info globally and for any active seasonbalancesreturn the users points and XP balancesquestsreturn the users recently completed questsshopreturn the users recently purchased shop itemsrewardsreturn the users latest earnings from your reward rulestokensreturn what tokens the user holds (scoped to your collections)
The more data you request, the slower the response will be. Only request what you need.
| Type | string |
| Required | No |
| Limitations | Must either be empty (account,balances) or account, experience, balances quests, shop, rewards, or tokens separated by a comma. |
| Examples | "account,balances" |
limit
The number of quests and shop activity items to return.
| Type | int |
| Required | No |
| Limitations | Default 100. Can not be more than 300. |
| Examples | 100 |
cursor
Pagination key returned by our API to fetch the next set of results.
Pagination does not work when include is set to all. You must either specify quests OR shop.
| Type | string |
| Required | No |
| Limitations | Does not work if include=all |
| Examples | 100 |
rewardedAfter
Filter rewards to only include those rewarded after this timestamp.
| Type | string |
| Required | No |
| Limitations | Must be a valid ISO 8601 datetime string |
| Examples | "2025-05-03T11:13:21.802Z" |
rewardedBefore
Filter rewards to only include those rewarded before this timestamp.
| Type | string |
| Required | No |
| Limitations | Must be a valid ISO 8601 datetime string |
| Examples | "2025-05-03T11:13:21.802Z" |
Response
- Success (2XX)
- Failure (4XX)
{
"users": [
{
"account": {
"address": "string",
"discordUser": { // object can be null
"id": "string",
"username": "string",
"avatarUrl": "string"
},
"twitterUser": { // object can be null
"id": "string",
"username": "string",
"displayName": "string",
"profileImageUrl": "string"
},
"telegramUser": { // object can be null
"id": "string",
"username": "string"
},
"mintAddress": "string" | null, // users secondary wallet
"shippingAddress": { // object can be null
"addressOne": "string",
"addressTwo": "string",
"addressThree": "string",
"townOrCity": "string",
"state": "string",
"postCodeOrZipCode": "string",
"country": "string",
"deliveryNotes": "string"
},
"geoHashString": "string", // see https://en.wikipedia.org/wiki/Geohash
"geoLocation": { // can be null
"latLng": {
"latitude": decimal,
"longitude": decimal
},
"placeName": {
"place": "string",
"region": "string",
"country": "string"
}
},
"username": "string",
"hasSetUsernameBefore": boolean,
"avatarUrl": "string",
"hasSetAvatarBefore": boolean,
"bannerUrl": "string",
"hasSetBannerBefore": boolean,
"ensSubdomain": "string", // can be null
"ensSubdomainCost": "string", // can be null
"ensSubdomainLastChanged": "string", // can be null
"emailAddress": "string",
"emailVerified": boolean,
"emailNotifications": {
"platformNotifications": boolean,
"newsletterNotifications": boolean
},
"isFirstLogin": boolean,
"primaryAddress": "string" // can be null, if set then you should query the users profile on this value
"secondaryAddresses": [ // can be null
"string",
"string"
],
"membershipNumber": "string"
},
"balances": { // can be null if the user has no balances (new user, etc)
"address": "string",
"balances": [
{
"currencyId": "string", // guid
"currencyName": "string",
"currencySymbol": "string",
"balance": decimal
}
]
},
"experience": {
"season": int, // currently active season number (or 0 for none)
"experiencePoints": int, // number of xp points for that active season
"experiencePointsGlobal": int, // number of xp points globally
"address": "string"
},
"quests": [
{
"questId": "string",
"questName": "string",
"questDescription": "string",
"questType": "string",
"rewardCurrencyId": "string",
"rewardCurrencyName": "string",
"rewardCurrencySymbol": "string",
"rewardAmount": decimal,
"rewardPayoutType": "string",
"bonusXpToReward": integer,
"status": "status",
"rewardedAt": "string" // in iso8601 format
}
]
"rewards": { // can be null if the user has no earnings (new user, etc)
"accountAddress": "string",
"earningDate": "string", // in iso8601 format
"currencyEarnings": [
{
"currencyId": "string",
"currencyName": "string",
"currencySymbol": "string",
"autoClaim": boolean,
"totalEarned": decimal,
"totalClaimed": decimal,
"breakdowns": [
{
"ruleId": "string",
"ruleName": "string",
"rewardType": "string",
"currencyId": "string",
"amountEarned": decimal,
"ruleReward": decimal
}
]
}
]
},
"shopActivity": [ // can be null
{
"id": "string",
"shopItemId": "string",
"transactionType": "string", // SaleTransaction, BidTransaction, or RaffleEntryTransaction
"address": "string",
"time": "string" // in iso8601 format
}
],
"tokens": [ // can be empty
{
"tokenId": "string",
"contract": "string",
"metadata": key-value pair
}
]
}
],
"paginationToken": "string"
}
{
}
Codes
| Code | Success | Description |
|---|---|---|
| 2XX | Yes | Your request was successfully processed and data is returned. |
| 4XX | No | Your request failed, most likely we were unable to match the wallet address to an account. |
| 5XX | No | The entire transaction failed due to a server-side error. If the error continues after several attempts, please report this to the On3 support team. |