OAuth
Setup
Create a new application from the Developer settings page in your verified Nifty Gateway account. To become verified, you only need to sign up to be an Authorized Seller - it shouldn’t take more than a couple of minutes.
You'll need to enter:
- Application name
- Authorization Code (server-assisted) grant or the less secure Implicit (frontend-only) grant
- Allowed redirect URI(s)
You might want to request two applications: one that can only redirect to your production site, and a second one that can redirect to localhost or other test servers.
If you requested Implicit grant, you'll receive only a Client ID back. If you requested Authorization Code, you'll receive a Client ID and a Client Secret.
Usage
-
Make a "Sign in with Nifty Gateway" button. A branded/logo button for this purpose is coming soon but is not yet available.
-
Send the user to https://niftygateway.com/authorize, with the following query string parameters:
scope
: one or more scopes, separated by spaces or +sprofile:read
for basic access to the current user's profileemail:read
for access to the current user's email address- Most other data you'd need is publicly available once you know who the current user is, but if there's anything in particular you need please contact Eric Winer at eric@gemini.com.
client_id
: the unique Client ID for your applicationredirect_uri
: one of the valid redirect URIs for your applicationresponse_type
: usetoken
for Implicit,code
for Authorization Coderesponse_mode
: optional; defaults tofragment
for Implicit,query
for Authorization Codestate
andnonce
: optional but recommended; see the OAuth2 specification for more detail
An example URL which has email:read and profile:read in scope is:
While one with only profile:read in scope is:
Try them out!
-
After signing in and authorizing a connection to your application, the user will be sent back to
redirect_uri
with a #fragment or ?query_string appended containing the access token or authorization code. -
As per the OAuth2 spec, please verify
state
and, if using the Authorization Code method, make a POST request* from your backend server to https://api.niftygateway.com/oauth2/token/ to exchange the authorization code for an access token (see https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type#exchange-the-authorization-code-for-an-access-token).-
- This POST request MUST be sent as
application/x-www-form- urlencoded
, not JSON
- This POST request MUST be sent as
-
-
Once you've obtained an access token, API calls can be made with an
Authorization: Bearer [access-token]
header.
APIs
All APIs are accessible at https://api.niftygateway.com/. For APIs which require authentication, add an Authorization: Bearer [access-token]
header. There are rate limits imposed; please contact us if you're hitting rate limits and we can discuss further details.
GET /v1/me/: Current User Information
- Required scope:
profile:read
- Query string parameters: none
- Example response for https://api.niftygateway.com/v1/me/:
{
"username": "tommy", // i.e. <https://niftygateway.com/profile/tommy>
"name": "Tommy K",
"profilePicUrl": "<https://res.cloudinary.com/nifty-gateway/image/upload/v1625617848/uiflc4iaky3k6hh8nrqh.png>"
}
GET /v1/me/email/: Current User Email
- Required scope:
email:read
- Query string parameters: none
- Example response for https://api.niftygateway.com/v1/me/email/:
{
"email": "tommy@niftygateway.com"
}
GET /v1/users/[username]/nifties/: Nifties for User
Returns information about all nifties owned by the given user.
- Required scope: none (this is a public API)
- Query string parameters:
contractAddress
: string, optional. If provided, will only show Nifties for that contract address.limit
: numeric, optional. If provided, will show only the specified number of nifties.offset
: numeric, optional. If provided, will skip the specified number of nifties in the result.
- Example response for https://api.niftygateway.com/v1/users/tommy/nifties/?limit=2:
{
"count": 64,
"next": "<https://api.niftygateway.com/v1/users/tommy/nifties/?limit=2&offset=2>",
"previous": null,
"results": [
{
"contractAddress": "0x8c167a1dbf8e19d18705382d6a457491589f9598",
"tokenId": "33400030081",
"name": "YOU RESPECTED ME #81/100",
"creator": {
"username": "billelis",
"name": "Billelis",
"profilePicUrl": "<https://res.cloudinary.com/nifty-gateway/image/upload/v1606249630/aekrzlaq22zxnyvairbo.jpg>"
},
"owner": {
"username": "tommy",
"name": "tommyk.eth",
"profilePicUrl": "<https://res.cloudinary.com/nifty-gateway/image/upload/v1625617848/uiflc4iaky3k6hh8nrqh.png>"
}
},
{
"contractAddress": "0xc92ceddfb8dd984a89fb494c376f9a48b999aafc",
"tokenId": "3152",
"name": "Creature #3152",
"creator": {
"username": "creatureworld",
"name": "Creature World",
"profilePicUrl": "<https://res.cloudinary.com/nifty-gateway/image/upload/v1630692687/wtalars9l78kggjfqeqt.jpg>"
},
"owner": {
"username": "tommy",
"name": "tommyk.eth",
"profilePicUrl": "<https://res.cloudinary.com/nifty-gateway/image/upload/v1625617848/uiflc4iaky3k6hh8nrqh.png>"
}
}
]
}
GET /v1/creators/[username]/collectors: Nifties for Creator
<aside> 💡 Not live yet, but coming soon!
</aside>
Returns ownership information for all nifties created by the given creator and currently stored on Nifty Gateway.
- Required scope: none (this is a public API)
- Query string parameters:
limit
: numeric, optional. If provided, will show only the specified number of nifties.offset
: numeric, optional. If provided, will skip the specified number of nifties in the result.
- Response format is the same as
/v1/users/[username]/nifties
. - Example response for `https://api.niftygateway.com/v1/creators/beeple/collectors/?limit=2:
{
"count":833,
"next":"<https://api.niftygateway.com/v1/creators/beeple/collectors/?limit=2&offset=2>",
"previous":null,
"results":[
{
"contractAddress":"0xdd012153e008346591153fff28b0dd6724f0c256",
"tokenId":"100010004",
"name":"BIOLOGICAL COLLECTIBLE #4/100",
"creator":{
"name":"Beeple",
"username":"beeple",
"profilePicUrl":"<https://res.cloudinary.com/nifty-gateway/image/upload/v1603980606/ntvv2nxvux3wfhbqta0h.jpg>"
},
"owner":{
"name":"DaNichi Editions",
"username":"danichi_editions",
"profilePicUrl":"<https://nftgimagebucket.s3-us-west-1.amazonaws.com/nifty_default_pic1.jpg>",
"airdropAddressEth":null
}
},
{
"contractAddress":"0xdd012153e008346591153fff28b0dd6724f0c256",
"tokenId":"100010027",
"name":"BIOLOGICAL COLLECTIBLE #27/100",
"creator":{
"name":"Beeple",
"username":"beeple",
"profilePicUrl":"<https://res.cloudinary.com/nifty-gateway/image/upload/v1603980606/ntvv2nxvux3wfhbqta0h.jpg>"
},
"owner":{
"name":"DaNichi Editions",
"username":"danichi_editions",
"profilePicUrl":"<https://nftgimagebucket.s3-us-west-1.amazonaws.com/nifty_default_pic1.jpg>",
"airdropAddressEth":null
}
}
]
}
Use Cases
Verify NFT Ownership in a Project
- Use OAuth2 as described above to make a "Sign in with Nifty Gateway" button. Request the
profile:read
scope. - Obtain an access token for the user.
- Call https://api.niftygateway.com/v1/me/ with an
Authorization: Bearer [access-token]
header to retrieve the user's username. - Call https://api.niftygateway.com/v1/users/**[username]**/nifties/?contractAddress=**[contract]** (a public API) to see the nifties in that contract, owned by the current user.
Add NFT Owners to your Mailing List
- Use OAuth2 as described above to make a "Sign in with Nifty Gateway" button. Request the
profile:read+email:read
scope. - Obtain an access token for the user. The authorization dialog on niftygateway.com will prompt the user to share their email address with you.
- Call https://api.niftygateway.com/v1/me/email/ with an
Authorization: Bearer [access-token]
header to retrieve the user's email address.
Track All Owners in a Project
Poll the /v1/creators/[username]/collectors
API occasionally to see who owns NFTs by a certain artist.
Note: If you’re a creator and need a list of wallets belonging to your NG collectors (for airdrops or whitelists for example), see the publicly accessible API below⬇️
https://niftygateway.readme.io/docs/how-to-airdrop-nfts-to-users-with-nifty-gateway-custody-accounts
❤️ All of this functionality was built because of feedback from creators and developers like you! Please don't hesitate to reach out at eric@gemini.com with any ideas or suggestions.