SDK HTTP API

Reference documentation for routes, request formats, and response structures. Actions requiring the player's private key are not included in this documentation. For those operations, use the @skinsprotocol/sdk.

Base URL (staging)

https://sdk-api-production-07d0fe8b0717.herokuapp.com/

Conventions

  • Addresses are 0x + 40 hex characters.
  • Big integers may appear as decimal strings or numbers where the handler uses parseBigInt.
  • Errors: often 400 with { "error": "message" }.
  • POST routes that perform writes use the server operator wallet, not the end-user's key.

Chain Addresses

Environment: Base (mainnet)
Marketplace address: 0xef7f7820a001aabAc5E0979b175C9ff8Af3Dd4ec
NFT address: 0xBeAfD8600ee870Bb3D5BbE5d248DBBE3FA2B82f0

ERC-20

POST routes are signed with the server operator wallet, not the end-user’s key. For player-wallet flows, use `@skinsprotocol/sdk` in the client.

GET

balanceOf

SDK: balanceOf

Returns an account's token balance for the given ERC-20 contract.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/token/balance-of

Path

/v1/token/balance-of

Inputs

**Query:** `tokenAddress: 0x{string}`, `account: 0x{string}`

Response 200

{ "balance": "<decimal string>" }
GET

allowance

SDK: allowance

Returns the amount of tokens the owner has allowed the spender to transfer on their behalf.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/token/allowance

Path

/v1/token/allowance

Inputs

**Query:** `tokenAddress: 0x{string}`, `owner: 0x{string}`, `spender: 0x{string}`

Response 200

{ "allowance": "<decimal string>" }
POST

transferFrom

SDK: transferFrom

Transfers tokens from `from` to `to` using allowance, executed by the operator wallet.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/token/transfer-from

Path

/v1/token/transfer-from

Inputs

**Body:** `tokenAddress: 0x{string}`, `from: 0x{string}`, `to: 0x{string}`, `amount: <decimal string>`

Response 200

{ "transactionHash": "0x…" }

NFT

The `owned-count` route is implemented for **ERC-721** only. Marketplace approval via POST `/v1/nfts/approve` uses the marketplace address from chain deployments for the configured `CHAIN`.

POST

grantMinter

SDK: grantMinter

Grants the minter role on the NFT collection contract (operator-signed).

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/grant-minter

Path

/v1/nfts/grant-minter

Inputs

**Body:** `contractAddress: 0x{string}`, `minter: 0x{string}`

Response 200

{ "transactionHash": "0x…" }
POST

mint

SDK: mint

Mints a new token to `to` with the given `tokenURI`; returns transaction hash, metadata CID, and decimal string `tokenId`.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/mint

Path

/v1/nfts/mint

Inputs

**Body:** `contractAddress: 0x{string}`, `to: 0x{string}`, `tokenURI: string`

Response 200

{ "transactionHash", "metadataCid", "tokenId" } — `tokenId` is a decimal string
GET

balanceOf (ERC-721)

SDK: balanceOf

Returns how many ERC-721 tokens `account` holds for the collection at `contractAddress`.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/owned-count/:contractAddress/:account

Path

/v1/nfts/owned-count/:contractAddress/:account

Inputs

**Path:** `contractAddress: 0x{string}`, `account: 0x{string}`

Response 200

{ "balance": "<decimal string>" }
GET

ownerOf

SDK: ownerOf

Returns the owner wallet for a specific `tokenId` in the collection.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/owner/:contractAddress/:tokenId

Path

/v1/nfts/owner/:contractAddress/:tokenId

Inputs

**Path:** `contractAddress: 0x{string}`, `tokenId: <decimal string>`

Response 200

{ "owner": "0x…" }
GET

isApprovedForAll

SDK: isApprovedForAll

Returns whether `operator` is approved to move all tokens of `owner` for this ERC-721 collection.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/is-approved-for-all/:contractAddress/:owner/:operator

Path

/v1/nfts/is-approved-for-all/:contractAddress/:owner/:operator

Inputs

**Path:** `contractAddress: 0x{string}`, `owner: 0x{string}`, `operator: 0x{string}`

Response 200

{ "isApprovedForAll": boolean }
GET

getApproved

SDK: getApproved

Returns the single-token approval address for `tokenId`, if set.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/nfts/approved/:contractAddress/:tokenId

Path

/v1/nfts/approved/:contractAddress/:tokenId

Inputs

**Path:** `contractAddress: 0x{string}`, `tokenId: <decimal string>`

Response 200

{ "approved": "0x…" }

Marketplace

These routes are read-only. Writes (`createAsk`, `acceptBid`, etc.) are available on `@skinsprotocol/sdk` with the user’s signing wallet. Ask/bid objects serialize bigints as decimal strings and include `tokenId`, `amount`, `currency`, `pricePerUnit`, `deadline`, `isActive`, plus `seller` (ask) or `buyer` (bid).

GET

getCollectionType

SDK: getCollectionType

Returns the marketplace collection type for the NFT collection address.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/marketplace/collection-type/:contractAddress

Path

/v1/marketplace/collection-type/:contractAddress

Inputs

**Path:** NFT collection `contractAddress: 0x{string}`

Response 200

{ "collectionType": number }
GET

getRoyalty

SDK: getRoyalty

Returns royalty receiver and fraction for the given token in the collection.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/marketplace/royalty/:contractAddress/:tokenId

Path

/v1/marketplace/royalty/:contractAddress/:tokenId

Inputs

**Path:** `contractAddress: 0x{string}`, `tokenId: <number>`

Response 200

{ "royalty": { "receiver", "royaltyFraction" } } — fraction as decimal string
GET

getAsk

SDK: getAsk

Fetches a single ask listing by collection address and ask identifier.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/marketplace/asks/:contractAddress/:askId

Path

/v1/marketplace/asks/:contractAddress/:askId

Inputs

**Path:** collection `contractAddress: 0x{string}`, `askId: <number>`

Response 200

{ "ask": { … } }
GET

getBid

SDK: getBid

Fetches a single bid by collection address and bid identifier.

URL

https://sdk-api-production-07d0fe8b0717.herokuapp.com/v1/marketplace/bids/:contractAddress/:bidId

Path

/v1/marketplace/bids/:contractAddress/:bidId

Inputs

**Path:** collection `contractAddress: 0x{string}`, `bidId: <number>`

Response 200

{ "bid": { … } }