Skip to main content

Nifty Gateway OAuth & Public API

  • Updated

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:

  1. Application name
  2. Authorization Code (server-assisted) grant or the less secure Implicit (frontend-only) grant
  3. 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

  1. Make a "Sign in with Nifty Gateway" button. A branded/logo button for this purpose is coming soon but is not yet available.

  2. Send the user to https://niftygateway.com/authorize, with the following query string parameters:

    1. scope: one or more scopes, separated by spaces or +s
      1. profile:read for basic access to the current user's profile
      2. email:read for access to the current user's email address
      3. 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.
    2. client_id: the unique Client ID for your application
    3. redirect_uri: one of the valid redirect URIs for your application
    4. response_type: use token for Implicit, code for Authorization Code
    5. response_mode: optional; defaults to fragment for Implicit, query for Authorization Code
    6. state and nonce: optional but recommended; see the OAuth2 specification for more detail

    An example URL which has email:read and profile:read in scope is:

    https://niftygateway.com/authorize?scope=email:read+profile:read&client_id=9ug7yQQnJ4DH5KB81DQBrhMu0mnVu0vPS5UyH7S1&redirect_uri=http://localhost:3000&response_type=token

    While one with only profile:read in scope is:

    https://niftygateway.com/authorize?scope=profile:read&client_id=9ug7yQQnJ4DH5KB81DQBrhMu0mnVu0vPS5UyH7S1&redirect_uri=http://localhost:3000&response_type=token

    Try them out!

  3. 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.

  4. 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

  5. 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

{
  "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

{
  "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

  1. Use OAuth2 as described above to make a "Sign in with Nifty Gateway" button. Request the profile:read scope.
  2. Obtain an access token for the user.
  3. Call https://api.niftygateway.com/v1/me/ with an Authorization: Bearer [access-token] header to retrieve the user's username.
  4. 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

  1. Use OAuth2 as described above to make a "Sign in with Nifty Gateway" button. Request the profile:read+email:read scope.
  2. Obtain an access token for the user. The authorization dialog on niftygateway.com will prompt the user to share their email address with you.
  3. 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.

Related articles