Use this file to discover all available pages before exploring further.
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 strongly recommend using Rust for production apps — it offers the most mature tooling, best performance, and the strongest safety guarantees when handling real assets. If you are 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
🐹 GO
# 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
# 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
# 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
Creating a project using near-go createThis will generate a project with the following structure:
auction/└── contract/ ├── go.mod # Go module definition with near-sdk-go dependency ├── go.sum └── main.go # Main contract file — replace this with the auction contract below
cd auction/contract
For this tutorial we chose to name the project auction, but feel free to use any name you prefer
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
🐹 GO
cargo test
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
uv run pytest
near-go test project
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
cargo near build non-reproducible-wasm
npm run build
# 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.
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:
# 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:
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):
# 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.
# 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.
We strongly recommend Rust for production apps — it provides the most mature tooling, best performance, and strongest safety guarantees when handling real assets on-chain. If you are prototyping or learning, you can use JavaScript, Python, or Go.
