Postman API Suite

We are happy to share our Web3 Services Postman collections with you! If you are not familiar with Postman, it is one of the easiest ways to send API requests and try out Circle’s APIs. Each of our Postman collections contains templated requests that you can use to start testing Circle’s W3S APIs.

How It's Organized

We’ve created a Web3 Services Postman Workspace that includes one collection per product i.e. Programmable Wallets, Smart Contract Platform (coming soon!). Within each of these collections are folders that are organized in a way that matches our API References.

How To Use It

Start by selecting Run in Postman below. From there, you can then choose to fork the collection to your workspace, view the collection in the public workspace, or import the collection into Postman.

  1. Fork: Creates a copy of the collection while maintaining a link to the parent.
  2. View: Allows you to quickly try out the API without having to import anything into your Postman suite.
  3. Import: Creates a copy of the collection but does not maintain a link to Circle’s copy.
CollectionRun it!
Programmable WalletsRun in Postman
Smart Contract PlatformRun in Postman

Additional Configuration


For authorization, you can paste your API key in the “Authorization” tab of the collection, as shown in the image below. If you do not have an API Key, you can acquire one by signing up for a Circle Developer account here. If you’d like to store your API key as a variable for more advanced testing, you can learn more in Postman’s variables guide.

Entity Secret

If you’re using Developer-Controlled wallets, you’ll need to generate a unique 32-byte entity secret. The guide on how to do so can be found here. Once you’ve registered your entity secret in the dashboard of your Circle Developer account, you can add your hex-encoded entity secret (not the encrypted entity secret ciphertext) as the variable value shown below.

For security purposes, Circle enforces uniqueness for your entity secret for each request you make. The helper scripts included in the Postman collection will re-encrypt the entity secret ciphertext you provided from the step above automatically before each call!

To enable this setup, run the “Get public key for entity” request one time. This will set your entity public key as a variable that will be used to encrypt your entity secret.

Variables & Helper Scripts


Variable NamebaseUrl
Variable Value
Originating APIN/A
API(s) using variableAll
DescriptionCircle's API URL for our Web3 Services platform.


Variable Namehex-encoded-entity-secret
Variable Valueyour hex-encoded entity secret
Originating APIN/A
API(s) using variableAll Developer-Controlled Wallets calls
DescriptionUnique 32-byte entity secret generated and encoded by the developer.


Variable Nameentity-public-key
Variable Valuedata.publicKey
Originating APIGET /config/entity/publicKey
API(s) using variableN/A
DescriptionThe RSA public key associated with your Circle Developer account. Used to encrypt the encoded entity secret.


Variable NameX-user-token
Variable Valuedata.userToken
Originating APIPOST /users/token
API(s) using variableAll User-Controlled Wallets calls
DescriptionThe temporary session token generated each time a user is active. Must be regenerated for each session.


Variable NamechallengeId
Variable Valuedata.challengeId
Originating APIPOST /user/initialize
POST /user/pin
PUT /user/pin
POST /user/pin/restore
API(s) using variableGET /user/challenges/:id
DescriptionThe unique UUID that corresponds to the various PIN flows. Passed in the User-Controlled Wallets SDK to complete each flow.

{blockchain}.{TOKEN SYMBOL}

Variable Name{blockchain}.{TOKEN SYMBOL}
Variable Valuedata.tokenBalances[n]
Originating APIGET /wallets/:id/balances
API(s) using variableAll Monitored Tokens/Token Lookup calls
DescriptionThe name of this variable is the blockchain of the token in lowercase followed by the token symbol in all caps. The variable value is the unique UUID associated with the token.


Variable NameuserId
Variable ValueUser ID
Originating APIPOST /users
API(s) using variablePOST /users/token
GET /users/:id
DescriptionThe unique UUID associated with each user. Unlike the user token, this value is static and does not expire or rotate.


Variable NameentitySecretCiphertext
Variable ValueEntity Secret Ciphertext
Originating APIN/A - Generated by pre-request script
API(s) using variableAll Developer-Controlled Wallets POST calls
DescriptionThe encoded entity secret linked to your Circle Developer Account, encrypted via your entity public key. The entity secret is re-encrypted before each POST call, as the same ciphertext cannot be used twice.


Variable NamewalletSetId
Originating APIPOST /developer/walletSets
API(s) using variableGET /walletSets/:id
PUT /developer/walletSets/:id
POST /developer/wallets
DescriptionThe unique UUID associated with each wallet set.


Variable NamewalletId
Variable ValueWallet ID
Originating APIPOST /developer/wallets
GET /wallets/:id
API(s) using variableGET /wallets/:id
GET /wallets/:id/balances
GET /wallets/:id/nfts
PUT /wallets/:id
POST /transactions/transfer/estimateFee
POST /transactions/contractExecution/estimateFee
POST /user/transactions/transfer
POST /user/transactions/contractExecution
POST /developer/transactions/transfer
POST /developer/transactions/contractExecution
DescriptionThe unique UUID associated with each wallet.


Variable NameimportedContractId
Variable ValueContract ID
Originating APIPOST /contracts/import
API(s) using variablePOST /contracts/:id/read
GET /contracts/:id
PATCH /contracts/:id
DescriptionThe unique, Circle-generated UUID associated with each imported smart contract.


Variable NamedeployedContractId
Variable ValueContract ID
Originating APIPOST /contracts/deploy
API(s) using variablePOST /contracts/:id/read
GET /contracts/:id
PATCH /contracts/:id
DescriptionThe unique, Circle-generated UUID associated with each deployed smart contract.