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.

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.

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 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 by using one of the scaffolding tools and following their instructions:

cargo near

img Creating a project using cargo near new

tip

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

What Does This Contract Do?​

The auction smart contract allows users to place bids, track the highest bidder and claim tokens at the end of the auction.

Do not worry about the code just yet — for now, it is enough to know that the most relevant function is bid, which allows users to place bids by attaching NEAR tokens:

Language Comparison​

LanguageBest ForBuild TimeEcosystem Maturity
JavaScript/TypeScriptRapid prototyping, web developersFast (~2s)Mature
RustProduction apps, performance-critical codeModerate (~30s)Most mature
PythonData science, AI integrationFast (~3s)Growing
GoBackend developers, microservicesFast (~5s)New

Choose JavaScript for quick experiments, Rust for production, Python for AI/data apps, Go if you're already a Go developer.

Besides bid, the contract exposes methods to initialize the auction (init), query the highest bidder (get_highest_bid), and claim tokens once the auction ends (claim).

Test the Contract​

Lets make sure the contract is working as expected by running its tests. Simply run the test command, the contract will then be compiled and deployed to a local sandbox for testing:

cargo test

Feel free to check the test files to see how they interact with the contract. In short, a local NEAR sandbox is created, the contract is deployed, and different methods are called to verify the expected behavior.

Build & Deploy the Contract​

Now that we know the tests are passing, let us deploy the contract! First, we need to compile it into WebAssembly:

cargo near build non-reproducible-wasm

Create an Account​

Let us now create a NEAR account where we will deploy the contract:

# Replace <contract-acc.testnet> with a name for your contract account
near create-account <contract-acc.testnet> --useFaucet
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 on WSL - or any other headless Linux environment - you might encounter issues when trying to create an account as the cli tries to save the keys into the system's 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

Deploy it!​

With the contract ready, we can now deploy it to the testnet account we created earlier:

near deploy <contract-acc.testnet> ./target/near/auction.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 us initialize the auction by setting when it ends and who receives the funds (the auctioneer):

# 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 <contract-acc.testnet> init "{\"end_time\": \"$FIVE_MINUTES_FROM_NOW\", \"auctioneer\": \"influencer.testnet\"}" --useAccount <contract-acc.testnet>
tip

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

Place a Bid​

We can now place a bid in the auction by calling the bid method while attaching some NEAR deposit. On each bid, the highest bid and bidder information will be recorded in the contract's storage.

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

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

Note how in this case we are using the <bidder-account.testnet> account (remember to rename it!) to call the bid function, while attaching a deposit of 0.01 NEAR as our bid

Get Highest Bid​

The get_highest_bid function only reads from the contract state, so it does not require a transaction or signature:

near view <contract-acc.testnet> get_highest_bid '{}'
Expected Output 
{
  "bidder": "<bidder-account.testnet>",
  "amount": "10000000000000000000000"
}
tip

Feel free to create as many bidder accounts as you want and place more bids to see how the highest bid changes!

Claim​

After the auction ends, anyone can call the claim method, which will transfer the highest bid amount to the auctioneer and end the auction.

near call <contract-acc.testnet> claim '{}' --useAccount <contract-acc.testnet>
Who won?

After the auction ends, the highest bidder can be determined by simply calling the get_highest_bid method again

Common Questions​

What about mainnet?​

You can deploy a contract to mainnet using the same commands, just make sure to create a mainnet account and use --networkId mainnet flag in the near CLI commands.

How much does it cost to deploy?​

The cost of deploying a contract depends on the contract's size, approximately 1Ⓝ ~100Kb.

Can I update a contract after deploying?​

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

Which language should I choose?​

To build production apps prefer Rust, as it offers the most mature tooling and best performance. Otherwise, if you are just prototyping or learning, you can choose between your favorite language between JavaScript, Python or Go.

How do I test without deploying?​

All languages support sandbox testing (shown in this guide). Tests run locally with a simulated NEAR environment.

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

Need Help?

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)