Deploy pre-audited smart contract templates on Arc with Circle Contracts.
This tutorial guides you through deploying smart contracts on Arc Testnet with
Circle Contracts.
You’ll create a
Circle Dev-Controlled SCA Wallet,
then deploy pre-audited contract templates (ERC-20, ERC-721, ERC-1155, Airdrop).
With SCA wallets,
Circle Gas Station
automatically sponsors your transaction fees on Arc Testnet.These pre-audited templates represent building blocks: ERC-20 for money and
liquidity, ERC-721 for identity and unique rights, ERC-1155 for scalable
financial instruments, and Airdrops for distributing incentives. To learn more
about available templates, visit the
Templates Overview
to review all templates and their options.
Circle Developer Account - Sign up on the
Developer Console
API Key - Create in the Console: Keys → Create a key → API key →
Standard Key
Entity secret: Generated and registered using the
Circle Console
or the
SDK
New to Circle dev-controlled wallets? See what credentials you need.
Circle wallets use three credentials. An API
key authenticates your
requests to Circle APIs. An entity
secret
authorizes each wallet operation. A wallet set
ID
groups your wallets.
Step 1. Set up your project
Before deploying any template, you need a working project and a funded
dev-controlled wallet on Arc Testnet. Complete the steps in this section once.
Then reuse the same wallet and credentials across all template deployments that
follow.
1.1. Create the project and install dependencies
Create a new directory. Navigate to it and start a new project with default
settings.
mkdir hello-arccd hello-arcnpm init -ynpm pkg set type=module# Add run scripts for wallet creation and contract deploymentnpm pkg set scripts.create-wallet="tsx --env-file=.env create-wallet.ts"npm pkg set scripts.deploy-erc20="tsx --env-file=.env deploy-erc20.ts"npm pkg set scripts.deploy-erc721="tsx --env-file=.env deploy-erc721.ts"npm pkg set scripts.deploy-erc1155="tsx --env-file=.env deploy-erc1155.ts"npm pkg set scripts.deploy-airdrop="tsx --env-file=.env deploy-airdrop.ts"
In the project directory, install the
Circle Dev-Controlled Wallets SDK
and the Circle Contracts SDK.
Dev-Controlled Wallets are Circle-managed wallets that your app controls using
APIs. You can deploy contracts and submit transactions without managing private
keys directly. You can also call the
Circle Wallets API and
Circle Contracts API
directly if you can’t use the SDKs in your project.
CIRCLE_API_KEY is your Circle Developer API key for Wallets and Contracts
API requests.
CIRCLE_ENTITY_SECRET is your registered entity secret used to authorize
developer-controlled wallet operations.
CIRCLE_WEB3_API_KEY is the Python SDK compatibility variable and should use
the same value as CIRCLE_API_KEY.
The npm run commands in this tutorial load variables from .env using Node.js
native env-file support.
Prefer editing .env files in your IDE or editor so credentials are not
leaked to your shell history.
This tutorial adds runtime values such as wallet IDs, transaction IDs, and
contract IDs later in the flow. Keep those derived values aligned with the
script outputs as you progress through the deployment steps.
Step 2. Set up your wallet
In this step, you create a dev-controlled wallet and fund it for contract
deployment on Arc Testnet. If you already have a funded Arc Testnet
dev-controlled wallet, skip to
the contract templates section.
2.1. Create a wallet
Import the Wallets SDK and start the client with your API key and Entity Secret.
Dev-controlled wallets are created in a
wallet set.
The wallet set is the source from which wallet keys are derived.
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";const client = initiateDeveloperControlledWalletsClient({ apiKey: process.env.CIRCLE_API_KEY, entitySecret: process.env.CIRCLE_ENTITY_SECRET,});// Create a wallet setconst walletSetResponse = await client.createWalletSet({ name: "Wallet Set 1",});// Create a wallet on Arc Testnetconst walletsResponse = await client.createWallets({ blockchains: ["ARC-TESTNET"], count: 1, walletSetId: walletSetResponse.data?.walletSet?.id ?? "", accountType: "SCA",});console.log(JSON.stringify(walletsResponse.data, null, 2));
from circle.web3 import utils, developer_controlled_walletsimport osimport jsonclient = utils.init_developer_controlled_wallets_client( api_key=os.getenv("CIRCLE_API_KEY"), entity_secret=os.getenv("CIRCLE_ENTITY_SECRET"))wallet_sets_api = developer_controlled_wallets.WalletSetsApi(client)wallets_api = developer_controlled_wallets.WalletsApi(client)# Create a wallet setwallet_set = wallet_sets_api.create_wallet_set( developer_controlled_wallets.CreateWalletSetRequest.from_dict({ "name": "Wallet Set 1" }))# Create a wallet on Arc testnetwallet = wallets_api.create_wallet( developer_controlled_wallets.CreateWalletRequest.from_dict({ "blockchains": ["ARC-TESTNET"], "count": 1, "walletSetId": wallet_set.data.wallet_set.actual_instance.id, "accountType": "SCA" }))print(json.dumps(wallet.data.to_dict(), indent=2))
Run the script:
npm run create-wallet
python create_wallet.py
Response:
If you’re calling the API directly, you’ll need two requests. One to create
the wallet
set.
One to create the
wallet.Be sure to replace the
Entity Secret ciphertext
and the idempotency key in your request. If you’re using the SDKs, this is
handled for you.
You should now have a newly created dev-controlled wallet. The API response will
look similar to the following:
Why SCA wallets? Smart Contract Accounts (SCA) on Arc Testnet work with
Gas Station to
automatically sponsor transaction fees. Learn more about Gas Station policies
and setup.
ERC-20
ERC-721
ERC-1155
Airdrop
Deploy an ERC-20 contract
ERC-20 is the standard for fungible tokens. Use this template for tokenized
assets, treasury instruments, governance tokens, or programmable money.
Step 3: Prepare for deployment
3.1. Get your wallet information
Retrieve your wallet ID from Step 2. Ensure:
Wallet custody type is Dev-Controlled
Blockchain is Arc Testnet
Account type is SCA (Smart Contract Account, recommended for Gas Station
compatibility)
Note your wallet’s address for subsequent steps.
3.2. Understand deployment parameters
Parameter
Description
idempotencyKey
A unique value to prevent duplicate requests.
name
The offchain contract name (visible in Circle Console only). Use MyTokenContract.
walletId
The ID of the wallet deploying the contract. Use your dev-controlled wallet ID.
templateId
The template identifier. Use a1b74add-23e0-4712-88d1-6b3009e85a86 for ERC-20. See Templates.
A successful response indicates deployment has been initiated, not
completed. Use the transactionId to check the deployment status in the next
step.
4.1. Check deployment status
You can check the status of the deployment from the
Circle Developer Console
or by calling
GET /transactions/{id}.After running the deployment script, copy the transactionId from the response
and update your .env file with TRANSACTION_ID={your-transaction-id}. Then
run the check-transaction script to verify deployment status.
After deployment completes, retrieve the contract address using
GET /contracts/{id}.After deployment completes, copy the contractIds[0] from the deployment
response and update your .env file with CONTRACT_ID={your-contract-id}. Then
run the get-contract script to retrieve the contract address.
Once your contract is deployed, you can interact with it from your application.
You’ll be able to view the contract both in the
Circle Developer Console
and on the Arc Testnet Explorer.
Initial Supply: The contract starts with 0 token supply at deployment. Use
the mintTo function to create tokens and assign them to addresses as needed.
Deploy an ERC-721 contract
ERC-721 is the standard for unique digital assets. Use this template for
ownership certificates, tokenized assets, unique financial instruments, or
distinct asset representation.
Step 3: Prepare for deployment
3.1. Get your wallet information
Retrieve your wallet ID from Step 2. Ensure:
Wallet custody type is Dev-Controlled
Blockchain is Arc Testnet
Account type is SCA (Smart Contract Account, recommended for Gas Station
compatibility)
Note your wallet’s address for subsequent steps.
3.2. Understand deployment parameters
Parameter
Description
idempotencyKey
A unique value to prevent duplicate requests.
name
The offchain contract name (visible in Circle Console only). Use MyTokenContract.
walletId
The ID of the wallet deploying the contract. Use your dev-controlled wallet ID.
templateId
The template identifier. Use 76b83278-50e2-4006-8b63-5b1a2a814533 for ERC-721. See Templates.
A successful response indicates deployment has been initiated, not
completed. Use the transactionId to check the deployment status in the next
step.
4.1. Check deployment status
Verify deployment with
GET /transactions/{id}.After running the deployment script, copy the transactionId from the response
and update your .env file with TRANSACTION_ID={your-transaction-id}. Then
run the check-transaction script to verify deployment status.
After deployment completes, retrieve the contract address using
GET /contracts/{id}.After deployment completes, copy the contractIds[0] from the deployment
response and update your .env file with CONTRACT_ID={your-contract-id}. Then
run the get-contract script to retrieve the contract address.
ERC-1155 is the standard for multi-asset token management. Use this template for
structured products, tiered assets, batch settlements, or managing diverse asset
portfolios.
Step 3: Prepare for deployment
3.1. Get your wallet information
Retrieve your wallet ID from Step 2. Ensure:
Wallet custody type is Dev-Controlled
Blockchain is Arc Testnet
Account type is SCA (Smart Contract Account, recommended for Gas Station
compatibility)
Note your wallet’s address for subsequent steps.
3.2. Understand deployment parameters
Parameter
Description
idempotencyKey
A unique value to prevent duplicate requests.
name
The offchain contract name (visible in Circle Console only). Use MyMultiTokenContract.
walletId
The ID of the wallet deploying the contract. Use your dev-controlled wallet ID.
templateId
The template identifier. Use aea21da6-0aa2-4971-9a1a-5098842b1248 for ERC-1155. See Templates.
A successful response indicates deployment has been initiated, not
completed. Use the transactionId to check the deployment status in the next
step.
4.1. Check deployment status
Verify deployment with
GET /transactions/{id}.After running the deployment script, copy the transactionId from the response
and update your .env file with TRANSACTION_ID={your-transaction-id}. Then
run the check-transaction script to verify deployment status.
After deployment completes, retrieve the contract address using
GET /contracts/{id}.After deployment completes, copy the contractIds[0] from the deployment
response and update your .env file with CONTRACT_ID={your-contract-id}. Then
run the get-contract script to retrieve the contract address.
The Airdrop template enables mass token distribution to many recipients. Use
this template for treasury distributions, stakeholder settlements, operational
payments, or programmatic capital allocation.
Step 3: Prepare for deployment
3.1. Get your wallet information
Retrieve your wallet ID from Step 2. Ensure:
Wallet custody type is Dev-Controlled
Blockchain is Arc Testnet
Account type is SCA (Smart Contract Account, recommended for Gas Station
compatibility)
Note your wallet’s address for subsequent steps.
3.2. Understand deployment parameters
Parameter
Description
idempotencyKey
A unique value to prevent duplicate requests.
name
The offchain contract name (visible in Circle Console only). Use MyAirdropContract.
walletId
The ID of the wallet deploying the contract. Use your dev-controlled wallet ID.
templateId
The template identifier. Use 13e322f2-18dc-4f57-8eed-4bddfc50f85e for Airdrop. See Templates.
A successful response indicates deployment has been initiated, not
completed. Use the transactionId to check the deployment status in the next
step.
4.1. Check deployment status
Verify deployment with
GET /transactions/{id}.After running the deployment script, copy the transactionId from the response
and update your .env file with TRANSACTION_ID={your-transaction-id}. Then
run the check-transaction script to verify deployment status.
After deployment completes, retrieve the contract address using
GET /contracts/{id}.After deployment completes, copy the contractIds[0] from the deployment
response and update your .env file with CONTRACT_ID={your-contract-id}. Then
run the get-contract script to retrieve the contract address.