CryptoStone API Doc

Integration reference for metadata, protocol views, contract reads, and CryptoStone app flows.

Integration Reference

CryptoStone API Doc

Protocol Views

CryptoStone exposes read-only views for metadata, GEMS dashboards, mining, wallet summaries, STONX access, and Arena activity. Value-moving actions remain wallet-confirmed app flows or direct contract calls.

Base URL

https://cryptostone.org

API Principle

Integration Note 1

Public APIs are intended for read-only dashboards, explorers, metadata readers, wallet summaries, and partner integrations.

API Principle

Integration Note 2

Wallet addresses are public blockchain identifiers. Do not submit seed phrases, private keys, recovery phrases, passwords, or sensitive personal data.

API Principle

Integration Note 3

Most live endpoints read Sepolia contracts, Redis cache, PostgreSQL records, or public blockchain logs. Cache status may be returned as part of the response.

API Principle

Integration Note 4

Mutation endpoints that create game actions, wallet processes, relayer jobs, reward claims, or transaction requests are not documented as public APIs.

API Principle

Integration Note 5

Mainnet API paths are expected to remain stable, while contract addresses and chain labels will move through environment configuration.

REST API

Public endpoints

GETPublicNFT Metadata

/api/nft/metadata/{tokenId}

OpenSea-compatible metadata endpoint for CryptoStone GEMS NFTs.

Example

GET /api/nft/metadata/27

Parameters

tokenId: numeric NFT token id. .json suffix is accepted.

Response fields

name
description
image
animation_url
external_url
metadata_status
attributes

Notes

Returns finalized metadata when available.
Returns on-chain fallback metadata while image/video generation is still revealing.
Invalid token ids return 400; unavailable metadata may return 503.

GETPublicGEMS

/api/gems/stats

Live GEMS supply, mint, claimable, refinery burn, and NFT transaction statistics.

Example

GET /api/gems/stats

Response fields

ok
source
updatedAt
result.totalGemsSupply
result.mintedGems
result.claimableToday
result.burnedByRefinery
result.nftTransactions30d
cache

Notes

Uses Sepolia contract reads with Redis caching and safe fallback data.

GETPublicGEMS

/api/gems/activity

Recent claim records, NFT transfer/listing/purchase/burn activity, top GEMS, and mined rarity counts.

Example

GET /api/gems/activity

Response fields

ok
source
updatedAt
result.claims
result.transactions
result.topGems
result.rarityCounts
cache

Notes

Combines database mint records and Sepolia NFT Transfer logs.

GETPublicMining

/api/gems/pool-status

Mining pool status for active GEMS pools, including supply, pool power, claimable counts, burn cost, and PoM values.

Example

GET /api/gems/pool-status

Response fields

ok
source
result.pools
result.garnet
cache

Notes

Inactive gemstone pools may be present in configuration but only live pools should be treated as open.

GETPublicWallet

/api/protocol/wallet-summary?wallet={address}

Protocol-level wallet summary for STONX and GEMS dashboard views.

Example

GET /api/protocol/wallet-summary?wallet=0x0000000000000000000000000000000000000000

Parameters

wallet: 0x-prefixed EVM wallet address.

Response fields

ok
source
updatedAt
result
cache

Notes

Invalid wallet addresses return 400.

GETPublicMining

/api/mining/wallet-summary?wallet={address}

Wallet mining positions, pool participation, claim readiness, and mining lifecycle summary.

Example

GET /api/mining/wallet-summary?wallet=0x0000000000000000000000000000000000000000

Parameters

wallet: 0x-prefixed EVM wallet address.

Response fields

ok
source
updatedAt
result
cache

Notes

Designed for the Mining page and external wallet dashboards.

GETPublicSTONX

/api/stone/private-sale

Direct STONX sale status, contract inventory, ETH raised, STONX sold, exchange rate, pause state, and recent purchases.

Example

GET /api/stone/private-sale

Response fields

ok
source
updatedAt
status.address
status.inventory
status.totalEthRaised
status.totalStonxSold
status.tokensPerEth
status.paused
purchases
cache

Notes

Read-only status endpoint. Buying STONX still requires wallet confirmation through the app.

GETPublicArena

/api/arena/leader-board

Arena leaderboard snapshots ordered by rank.

Example

GET /api/arena/leader-board

Response fields

rows
source

Notes

Returns database rows when available and seed/fallback rows when not.

GETPublicArena

/api/arena/my-score?wallet={address}

Arena score, recent matches, reward rights, and claimable STONX for a wallet.

Example

GET /api/arena/my-score?wallet=0x0000000000000000000000000000000000000000

Parameters

wallet: EVM wallet address. Empty wallet returns an empty score payload.

Response fields

wallet
gems
recentMatches
rewards
walletRewards
stats
source

Notes

Wallet addresses and Arena records may be public protocol data.

GETPublicArena

/api/arena/rooms

Arena room configuration and currently live match summary.

Example

GET /api/arena/rooms

Response fields

rooms
liveMatches
source

Notes

Used by Arena lobby views.

GETPublicArena

/api/arena/tables?roomType={DUEL|BATTLE|ARENA}&walletAddress={address}

List open Arena table rooms and active room for a wallet.

Example

GET /api/arena/tables?roomType=DUEL

Parameters

roomType: optional DUEL, BATTLE, ARENA, or TOURNAMENT.
walletAddress: optional EVM wallet address.

Response fields

ok
rooms
activeRoom

Notes

This is a lobby/listing read endpoint. Room creation and join actions are app actions, not public data APIs.

GETPublicArena

/api/arena/tables/{roomId}/state?walletAddress={address}

Read a table room state for a specific room id.

Example

GET /api/arena/tables/{roomId}/state

Parameters

roomId: Arena table room id.
walletAddress: optional wallet used to refresh player presence.

Response fields

ok
room

Notes

Presence refresh is app behavior. External consumers should avoid excessive polling.

GETPublicArena

/api/arena/matches/{matchId}

Read match detail for a specific Arena match id.

Example

GET /api/arena/matches/{matchId}

Parameters

matchId: Arena match id.

Response fields

match

Notes

Designed for match history, replay, and explorer-style views.

GETPublicArena

/api/arena/dao/treasury

Arena DAO treasury read model and allocation status.

Example

GET /api/arena/dao/treasury

Response fields

treasury
source

Notes

Read-only treasury visibility endpoint.

App Boundary

App action endpoints

POSTApp ActionArena

/api/arena/tables

Creates an Arena table room from the app UI.

Notes

Requires wallet-specific app state and should not be treated as a public integration API.

POSTApp ActionArena

/api/arena/tables/{roomId}/join

Joins a wallet to an Arena table room.

Notes

Subject to room state, entry fee confirmation, and anti-abuse checks.

POSTApp ActionArena

/api/arena/rewards/claim

Starts Arena reward withdrawal processing from the app UI.

Notes

Wallet confirmation and on-chain entitlement checks are required.

POSTApp ActionSwap

/api/uniswap/quote

App-side quote helper for supported swap UI.

Notes

Not a general-purpose public trading API.

Web3

Smart Contract API

Contract Reference

STONX Token

NEXT_PUBLIC_STONE_TOKEN_ADDRESS_V6

ERC-20 utility token used for Mining, Claim, Refinery, Marketplace, Arena entry, and ecosystem activity.

ABI

CryptoStoneTokenV6.json

Read functions

name
symbol
decimals
totalSupply
balanceOf
allowance

Write functions

approve
transfer
transferFrom

Events

Transfer
Approval

Notes

Batch flows should approve only the required amount where possible.

Contract Reference

GEMS NFT

NEXT_PUBLIC_GEMS_NFT_ADDRESS_V6

ERC-721 style NFT contract for mined and refined CryptoStone GEMS.

ABI

CryptoStoneGemNFTV6.json

Read functions

ownerOf
balanceOf
tokenURI
getGem
maxSupplyByStone
mintedByStone

Write functions

approve
setApprovalForAll
transferFrom
safeTransferFrom

Events

Transfer
Approval
ApprovalForAll

Notes

Metadata is served through the CryptoStone HTTPS metadata API and may finalize after mint confirmation.

Contract Reference

Garnet Mining Pool

NEXT_PUBLIC_GARNET_POOL_ADDRESS_V6

Active V6 mining pool contract for Garnet participation, claim readiness, and one-confirm minting.

ABI

CryptoStoneMiningPoolV6.json

Read functions

getPoolState
getPositionView
getUserMiningJobs
getUserClaimRequests
claimableCount
currentPoolPower
requiredPoM
claimBurnAmount

Write functions

joinPool
topUpPosition
withdrawUnlocked
claimGems
claimGemsWithEntropy

Events

PoolJoined
PoolToppedUp
PositionWithdrawn
DirectGemMinted
GemsBatchClaimed

Notes

Only Garnet is live. Other gemstone pools remain disabled until new contracts are opened.

Contract Reference

Refinery

NEXT_PUBLIC_REFINERY_ADDRESS_V6

Same-stone refinement contract that burns source NFTs and STONX to mint refined GEMS.

ABI

CryptoStoneRefineryV6.json

Read functions

COMMON_FEE
RARE_FEE
EPIC_FEE
refiningFee
previewRefinement
thresholds
tierGapModifierBps

Write functions

refine

Events

Refined

Notes

Refinery wallet flow should remain a one-confirmation batch where contract support allows it.

Contract Reference

Marketplace

NEXT_PUBLIC_MARKETPLACE_ADDRESS

Official STONX-denominated marketplace for listing, cancelling, and buying GEMS NFTs.

ABI

CryptoStoneMarketplaceV1.json

Read functions

activeListingByToken
getActiveListings
getListing
getListings
getListingsBySeller
totalActiveListings
totalListings

Write functions

createListing
cancelListing
buy

Events

ListingCreated
ListingCancelled
ListingSold

Notes

Public APIs expose marketplace activity through GEMS activity and NFT transfer classification.

Contract Reference

Private Sale

NEXT_PUBLIC_PRIVATE_SALE_ADDRESS_V6

Direct STONX acquisition contract used by Buy STONX Direct.

ABI

CryptoStonePrivateSaleV1.json

Read functions

quote
saleInventory
totalEthRaised
totalStonxSold
tokensPerWei
paused

Write functions

Events

Purchased

Notes

Public REST API exposes sale status only. Purchase requires wallet confirmation.

Contract Reference

Arena DAO Treasury

NEXT_PUBLIC_ARENA_DAO_TREASURY_ADDRESS_V6

Arena entry fee treasury and winner reward withdrawal accounting.

ABI

CryptoStoneArenaDaoTreasuryV6.json

Read functions

creditBalanceByPlayer
spentEntryAmountByPlayerAndRoom
claimedRewardAmountByPlayer
claimedRewardIds
usedCreditWithdrawalIds
totalCreditBalance
totalRewardClaimed
availableDaoBalance

Write functions

topUpCredit
withdrawCredit
spendEntryCredit
payEntryFee
claimRewards
withdrawDaoFunds

Events

ArenaCreditToppedUp
ArenaCreditWithdrawn
ArenaEntryFeePaid
ArenaRewardClaimed
ArenaDaoFundsWithdrawn
FeeSplitUpdated

Notes

User reward withdrawal must be limited to the connected wallet's entitlement.

Not Public

Internal endpoints

Internal

These endpoints support watcher finalization, wallet recovery, game action processing, real-time room state, and app-only transaction flows. They are intentionally excluded from public partner integration.

/api/mining/claim-relay/api/mining/claim-finalize/api/nft/mint-jobs/api/arena/entry-credit/api/arena/matches/{matchId}/action/api/arena/matches/{matchId}/replay/api/arena/realtime/{roomId}/api/arena/realtime/{roomId}/chat/api/arena/tables/{roomId}/player/api/arena/tables/{roomId}/start/api/arena/tables/{roomId}/leave/api/arena/tables/{roomId}