Skip to main content

Your First Smart Contract

Welcome! NEAR accounts can store small apps known as smart contracts. In this quick tutorial, we will guide you in creating your first contract on the NEAR testnet!

Join us in creating a friendly auction contract, which allows users to place bids, track the highest bidder and claim tokens at the end of the auction.

tip

Want to jump right into the code without setting up a local dev environment?

Checkout NEAR Playground for an easy-to-use online IDE w/ pre-configured templates.

NEAR Playground

Prerequisites​

Before starting, make sure to set up your development environment.

Working on Windows?

See our blog post getting started on NEAR using Windows for a step-by-step guide on how to set up WSL and your environment

# Install Node.js using nvm (more options in: https://nodejs.org/en/download)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install latest

# ⚠️ For Mac Silicon users only, Rosetta is needed to compile contracts
# /usr/sbin/softwareupdate --install-rosetta --agree-to-license

# Install NEAR CLI to deploy and interact with the contract
npm install -g near-cli-rs@latest
note

Some near-cli commands have two versions - a full one and a short one. If you want to explore all options provided by near-cli use the interactive mode.

Testnet Account

There is no need to have a testnet account to follow this tutorial.

However, if you want to create one, you can do so through a wallet, and use it from the near-cli by invoking near login.

Testnet tokens

Need some testnet tokens? Use the faucet to top-up your account.

Creating the Contract​

Create a smart contract by using one of the scaffolding tools and following their instructions:

  npx create-near-app@latest

img Creating a project using create-near-app

This will generate a project with the following structure:

hello-near
├── sandbox-test    # sandbox testing
│   └── main.ava.js
├── src             # contract's code
│   └── contract.ts
├── README.md
├── package.json    # package manager
└── tsconfig.json
tip

We recommend you to name your project hello-near for this tutorial, but feel free to use any name you prefer

The Contract​

The auction smart contract allows users to place bids, track the highest bidder and claim tokens at the end of the auction. Therefore it exposes following methods to interact with it:

  1. init: to initialize the contract with auction parameters
  2. bid: to place a bid in the auction
  3. claim: to claim tokens after the auction ends
  4. get_highest_bid: to fetch the highest bid and bidder information
  5. get_auction_end_time: to retrieve the auction end time
  6. get_auctioneer: to get the auctioneer's account ID
  7. get_claimed: to check if a bidder has claimed their tokens
tip

After finishing this tutorial, check our contract's anatomy page to learn more about the contract's structure

Test the Contract​

Building and testing the contract is as simple as running the test command. The contract will be compiled and the tests will be executed.

npm run test
Failing tests?

Make sure that you are using node v18, v20 or v22 - you can manage multiple versions using nvm - and that you have Rosetta installed on MacOS if you have an Apple Silicon processor.

In the background, these commands are calling the build tools for each language and using a Sandbox to test the contract.

Sandbox

Testing the contracts within a Sandbox allows you to understand how the contract will behave once deployed to the network while having total control over the testing environment.

Create a Testnet Account​

Now that you know the contract is passing the tests, let's create a testnet account in which to deploy the contract. near-cli supports two versions of some commands - full and short one. It's up to you which format you prefer, but full version provides more features.

# Replace <your-account-id.testnet> with a custom name
near create-account <your-account-id.testnet> --useFaucet
Example Result 
$> near create-account lovely-event.testnet --useFaucet
# New account "lovely-event.testnet" created successfully
tip

Remember that you can create a named account through any wallet (i.e. MyNearWallet) and then use it from the near-cli by invoking near login.

warning

When running the near account create-account command in a headless Linux environment (e.g., WSL), the save-to-keychain option may fail due to platform limitations. Use save-to-legacy-keychain instead of save-to-keychain to ensure compatibility.

Build the Contract​

When you are ready to create a build of the contract run a one-line command depending on your environment.

npm run build

Deploy the Contract​

Having our account created, we can now deploy the contract:

near deploy <created-account> ./build/hello_near.wasm

Congrats! Your contract now lives in the NEAR testnet network.

Interacting with the Contract​

To interact with your deployed smart contract, you can call its functions through the command line.

Initialize the Contract​

Let's start by initializing the contract with the auction parameters. The init method sets up the auction with an end time and the auctioneer's account ID. It can be called only by contract's account itself.

> near call <created-account> init '{"end_time": "<time-in-nanoseconds>", "auctioneer": "<created-account>"}' --accountId <created-account>
note

<auctioneer-account> should be replaced with the account ID of the auctioneer, which can be the same as <created-account> or a different account.

Place a Bid​

We can now place a bid in the auction using the bid method. This method allows users to place their bids by attaching a deposit. The highest bid and bidder information will be updated accordingly and will be stored on the contract's storage, and thus requires a user to sign a transaction in order to be executed (as well as attaching a deposit).

> near call <created-account> bid '{}' --deposit 0.01  --accountId <created-account>
tip

Notice that we are signing the transaction using <created-account>, so in this case, we are asking the contract's account to call its own function

Claim​

After the auction ends, the highest bidder can claim their tokens using the claim method. Actually, anyone can call this method on behalf of the highest bidder to transfer the tokens to them. This method requires a signed transaction but does not require any deposit.

> near call <created-account> claim '{}' --accountId <created-account>

Get Highest Bid​

The get_highest_bid function only reads from the contract's state, and can thus be called for free.

> near view <created-account> get_highest_bid '{}'

Get Auction End Time​

Same as get_highest_bid, the get_auction_end_time function only reads from the contract's state, and can thus be called for free.

> near view <created-account> get_auction_end_time '{}'

Get Auctioneer​

Same as get_highest_bid, the get_auctioneer function only reads from the contract's state, and can thus be called for free.

> near view <created-account> get_auctioneer '{}'

Get Claimed​

Same as get_highest_bid, the get_claimed function only reads from the contract's state, and can thus be called for free.

> near view <created-account> get_claimed '{}'

Moving Forward​

That's it for the quickstart tutorial. You have now seen a fully functional contract with a minimal user interface and testing.

To better understand the contract's structure, check our contract's anatomy page.

If you prefer to see more examples, check our examples page.

Looking for Support?

If you have any questions, connect with us on Telegram or Discord .

Happy coding! 🚀

Versioning for this article

At the time of this writing, this example works with the following versions:

  • node: 22.18.0
  • rustc: 1.86.0
  • near-cli-rs: 0.22.0
  • cargo-near: 0.16.1
  • Python: 3.13
  • near-sdk-py: 0.7.3
  • uvx nearc: 0.9.2
  • emscripten: 4.0.9 (required for Python contracts)