Your First Smart Contract

Welcome! NEAR accounts can store small apps known as smart contracts. In this tutorial, we’ll guide you through creating your first contract on the NEAR testnet. Create an auction contract that allows users to place bids, track the highest bidder, and claim tokens at the end of the auction.

Prefer an online IDE?

Want to jump right into the code without setting up a local dev environment?Check out NEAR Playground for an easy-to-use online IDE with pre-configured templates.

Prerequisites

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

# Install Rust: https://www.rust-lang.org/tools/install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Contracts will be compiled to wasm, so we need to add the wasm target
rustup target add wasm32-unknown-unknown

# Install NEAR CLI-RS to deploy and interact with the contract
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh

# Install cargo near to help building the contract
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh

Creating the contract

Create a smart contract with the cargo near scaffolding tool by following its instructions:

# Create a new contract called "auction"
cargo near new auction

Creating a project using cargo near new

For this tutorial, we chose to name the project auction, but feel free to use any name you prefer.

Build and deploy the contract

Let’s build the contract, create a NEAR testnet account, and deploy the contract to it.

# Run the sandbox tests to verify the contract works as expected
cargo test

# Build the contract
cargo near build non-reproducible-wasm

# Create a free testnet account, replace `<account.testnet>` with your desired account name
near create-account <account.testnet> --useFaucet

# Deploy the contract to the account
near deploy <account.testnet> ./target/near/auction.wasm

Already have a testnet account?If you already have a testnet account and would like to use it instead, you can log in with the command near login.

Got an error on Windows?

When working in WSL—or another headless Linux environment—you might encounter issues creating an account because the CLI tries to save keys to the system keychain.In such cases, you can try the following command to create the account:

near account create-account sponsor-by-faucet-service <your-account-id.testnet> autogenerate-new-keypair save-to-legacy-keychain network-config testnet create

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

Initialize the auction

The contract stores the highest bid, auction end time, auctioneer address, and a flag to track whether proceeds have been claimed. Its init function sets these values when the contract is first initialized: Initialize the auction by setting its end time and designating the auctioneer to receive the funds:

# Get a timestamp for 5 minutes from now (in nanoseconds)
FIVE_MINUTES_FROM_NOW=$(( $(date +%s%N) + 5 * 60 * 1000000000 ))

# Initialize the auction
near call <account.testnet> init "{\"end_time\": \"$FIVE_MINUTES_FROM_NOW\", \"auctioneer\": \"influencer.testnet\"}" --useAccount <account.testnet>

Feel free to replace influencer.testnet with any valid testnet account—this is where the winning bid will be sent.

Place and view bids

Place a bid in the auction by calling the bid method and attaching a NEAR deposit. The function checks whether the auction is ongoing and whether the bid is higher than the stored amount. If it is, the contract records the new bid and refunds the previous bidder.

# Create a new account to place the bid
near create-account <bidder-account.testnet> --useFaucet

# Place a bid of 0.01 NEAR
near call <account.testnet> bid '{}' --deposit 0.01  --useAccount <bidder-account.testnet>

In this example, use the <bidder-account.testnet> account (remember to rename it) to call the bid function and attach a deposit of 0.01 NEAR.

View the highest bid

The get_highest_bid function only reads from the contract state, so it does not require a transaction or signature. You can also use the contract’s other view methods to query the auction end time, auctioneer, and claim status:

near view <account.testnet> get_highest_bid '{}'

Expected Output

{
  "bidder": "<bidder-account.testnet>",
  "amount": "10000000000000000000000"
}

The amount is shown in yoctoNEAR, the smallest unit of NEAR. Since 1 NEAR equals 10^24 yoctoNEAR, the displayed amount is 0.01 NEAR.

Feel free to create more bidder accounts and place bids to see how the highest bid changes.

Claim the proceeds

After the auction ends, anyone can call the claim method. It transfers the amount of the highest bid to the auctioneer and ends the auction:

near call <account.testnet> claim '{}' --useAccount <account.testnet>

Who won?After the auction ends, you can determine the highest bidder by calling the get_highest_bid method again.

Frequently Asked Questions

What about mainnet?

You can deploy a contract to mainnet using the same commands. Create a mainnet account and use the --networkId mainnet flag in the near CLI commands.

How much does it cost to deploy?

The cost of deploying a contract depends on its size: approximately 1 Ⓝ per 100 KB.

Can I update a contract after deploying?

Yes. Redeploy with near deploy <account> <wasm-file>. The account stays the same, and the code is updated.

How do I test without deploying?

Use the sandbox tests shown in this guide. They run locally in a simulated NEAR environment.

Can I use a language other than Rust?

Yes. You can write smart contracts in any language that compiles to WebAssembly. Our documentation focuses on Rust, but community-maintained SDKs are available for other languages. See supported languages.

Moving forward

Create a Frontend

Check the auction frontend tutorial to learn how to build a simple web app that interacts with the auction contract.

Extend the Contract

Follow the auction NFT tutorial to award the highest bidder a Non-Fungible Token (NFT) and allow users to bid using Fungible Tokens (FT).

Learn More about the SDK

Check our Anatomy of a Contract page to understand the different components that make up a NEAR smart contract.

Versioning for this article

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

rustc: 1.86.0
near-cli-rs: 0.22.0
cargo-near: 0.16.1

Building Smart Contracts

DevKit

Tutorials

Your First Smart Contract

Prerequisites

Creating the contract

Build and deploy the contract

Initialize the auction

Place and view bids

View the highest bid

Claim the proceeds

Frequently Asked Questions

Moving forward

Create a Frontend

Extend the Contract

Learn More about the SDK

​Prerequisites

​Creating the contract

​Build and deploy the contract

​Initialize the auction

​Place and view bids

​View the highest bid

​Claim the proceeds

​Frequently Asked Questions

​Moving forward

Create a Frontend

Extend the Contract

Learn More about the SDK

Prerequisites

Creating the contract

Build and deploy the contract

Initialize the auction

Place and view bids

View the highest bid

Claim the proceeds

Frequently Asked Questions

Moving forward