Create your first contract using your favorite language.
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.
Which language should I use?In this tutorial we provide instructions to create contracts in multiple languages.We recommend using Rust for production apps due to its mature tooling. However, if you are just prototyping or learning, feel free to use JavaScript, Python, or Go!
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.
Before starting, make sure to set up your development environment.
🦀 Rust
🌐 JavaScript
🐍 Python
Copy
Ask AI
# Install Rust: https://www.rust-lang.org/tools/installcurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# Contracts will be compiled to wasm, so we need to add the wasm targetrustup target add wasm32-unknown-unknown# Install NEAR CLI-RS to deploy and interact with the contractcurl --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 contractcurl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh
Copy
Ask AI
# 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 | bashnvm 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 contractnpm install -g near-cli-rs@latest
Copy
Ask AI
# Install Python (if not already installed)# Use your system's package manager or download from https://www.python.org/downloads/# Install Emscripten (required for compiling Python contracts to WebAssembly)# For Linux/macOS:git clone https://github.com/emscripten-core/emsdk.gitcd emsdk./emsdk install latest./emsdk activate latestsource ./emsdk_env.sh# Add to your .bashrc or .zshrc for permanent installation:# echo 'source "/path/to/emsdk/emsdk_env.sh"' >> ~/.bashrccd ..# For Windows:# Download and extract: https://github.com/emscripten-core/emsdk# Then in Command Prompt:# cd emsdk# emsdk install latest# emsdk activate latest# emsdk_env.bat# Verify installation with:emcc --version# Install uv for Python package managementcurl -LsSf https://astral.sh/uv/install.sh | sh# Install NEAR CLI-RS to deploy and interact with the contractcurl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh```text</Tab><Tab title="🐹 GO">```bash#For Linux arm/x64sudo apt update && sudo apt upgrade -ysudo apt install -y build-essential curl wget git libssl-dev pkg-config checkinstallsudo apt install bison#For Macxcode-select --installbrew updatebrew install mercurialbrew install binaryenbash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)gvm install go1.25.4 -Bgvm use go1.25.4 --defaultcurl -LO https://github.com/vlmoon99/near-cli-go/releases/latest/download/install.sh && bash install.sh
The auction smart contract allows users to place bids, track the highest bidder and claim tokens at the end of the auction.Let’s take a look at the different components of the contract and how they work together to implement this functionality.
The contract stores the highest bid, auction end time, auctioneer address, and a flag to track if proceeds have been claimed. In order to set these parameters, an init function is provided, which must be called first to initialize the contract state.
In order to place a bid, users will need to call the bid function while attaching a deposit representing their bid amount.The bid function will then validate that the auction is ongoing, if the user bid a higher amount than the one stored, it will record the new bid and refund the previous bidder.
At all times, users can query the current state of the auction by calling its view methods (get_highest_bid, get_auction_end_time, get_auctioneer, get_claimed):
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:
🦀 Rust
🌐 JavaScript
🐍 Python
Copy
Ask AI
cargo test
Copy
Ask AI
npm run test
Failing tests?
Make sure that you are using node v24 / 22 / 20, and that you have installed Rosetta if you have a Mac with Apple Silicon
Copy
Ask AI
uv run pytest
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.
Now that we know the tests are passing, let us deploy the contract! First, we need to compile it into WebAssembly:
🦀 Rust
🌐 JavaScript
🐍 Python
🐹 GO
Copy
Ask AI
cargo near build non-reproducible-wasm
Copy
Ask AI
npm run build
Copy
Ask AI
# Build with nearc through the uv executor (no installation needed)uvx nearc contract.py
The above command will compile your Python contract into WebAssembly (WASM) that can be deployed to the NEAR blockchain.
The default nearc build configuration is appropriate for most contracts. You don’t need to install nearc separately as we’re using uvx to run it directly.
:::importantThis step requires Emscripten to be installed and accessible in your PATH. If you encounter errors during compilation, verify that Emscripten is properly installed with emcc --version.Common compilation errors and solutions:
emcc: command not found - Emscripten is not in your PATH. Run source /path/to/emsdk/emsdk_env.sh to add it temporarily.
error: invalid version of emscripten - Your Emscripten version might be too old. Try updating with ./emsdk install latest && ./emsdk activate latest.
Could not find platform micropython-dev-wasm32 - This typically means the Emscripten installation is incomplete or not properly activated.
:::
Copy
Ask AI
near-go build
Near Go SDK Build Process
All code from the main package, including imports from other modules, is combined into a single generated_build.go file.
The generated_build.go file is compiled into wasm32-unknown-unknown via TinyGo.
Customizing the BuildThe default near-go build command works for most standard projects, compiling source code from the current directory into main.wasm.However, if you want to specify a custom output name or inspect the intermediate glue code (generated JSON serialization and SDK integration wrappers) for debugging purposes, you can use the available flags:
Let us now create a NEAR account where we will deploy the contract:
Copy
Ask AI
# Replace <contract-acc.testnet> with a name for your contract accountnear 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:
Copy
Ask AI
near account create-account sponsor-by-faucet-service <your-account-id.testnet> autogenerate-new-keypair save-to-legacy-keychain network-config testnet create
Let us initialize the auction by setting when it ends and who receives the funds (the auctioneer):
Copy
Ask AI
# Get a timestamp for 5 minutes from now (in nanoseconds)FIVE_MINUTES_FROM_NOW=$(( $(date +%s%N) + 5 * 60 * 1000000000 ))# Initialize the auctionnear call <contract-acc.testnet> init "{\"end_time\": \"$FIVE_MINUTES_FROM_NOW\", \"auctioneer\": \"influencer.testnet\"}" --useAccount <contract-acc.testnet>
Feel free to replace influencer.testnet with any valid testnet account — this is where the winning bid will be sent
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.
Copy
Ask AI
# Create a new account to place the bidnear create-account <bidder-account.testnet> --useFaucet# Place a bid of 0.01 NEARnear call <contract-acc.testnet> bid '{}' --deposit 0.01 --useAccount <bidder-account.testnet>
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
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.
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.
