Use Smart Contract Platform

intent

deploy, import, query, and execute smart contracts across supported blockchains using circle's smart contract platform. use this skill when you need to launch new contracts from bytecode or templates, call contract functions (read-only or state-changing), or track emitted events via webhooks. works best for erc-20/721/1155 tokens, airdrops, and custom contracts compiled to the paris evm version or earlier.

inputs

circle sdk dependencies

• @circle-fin/smart-contract-platform npm package (initialize with initiateSmartContractPlatformClient)
• @circle-fin/developer-controlled-wallets npm package (initialize with initiateDeveloperControlledWalletsClient)

environment variables

• CIRCLE_API_KEY: circle api key in format PREFIX:ID:SECRET. generate in circle console. required for all operations.
• ENTITY_SECRET: registered entity secret for developer-controlled wallets. required for write transactions. store in secrets manager, never commit.

blockchain context

• target blockchain identifier (e.g., ARC-TESTNET, ETHEREUM, POLYGON). default to arc testnet for non-prod work.
• wallet id with sufficient gas funds (required only for write transactions). obtain from developer-controlled wallets after provisioning.

contract inputs (context-dependent)

• for bytecode deployment: compiled solidity bytecode (prefixed with 0x), contract abi (json array), constructor parameters matching abi types/order.
• for template deployment: template id (erc-20 a1b74add-23e0-4712-88d1-6b3009e85a86, erc-721 76b83278-50e2-4006-8b63-5b1a2a814533, erc-1155 aea21da6-0aa2-4971-9a1a-5098842b1248, airdrop 13e322f2-18dc-4f57-8eed-4bddfc50f85e), template parameters as json object.
• for imports: existing contract address on target blockchain, alphanumeric contract name.
• for interactions: contract id (from deployment or import), function name, function parameters (type-safe), ABI signature in format functionName(type1,type2,...) with no spaces.
• for event monitoring: contract id, event signature in format EventName(type1,type2,...).

external connections

• circle smart contract platform api endpoint (configured via sdk, no manual url required).
• webhook receiver url (for event monitoring, must be https and return 2xx status within 30 seconds).

procedure

step 1: initialize sdk clients

input: environment variables CIRCLE_API_KEY and ENTITY_SECRET.

import { initiateSmartContractPlatformClient } from "@circle-fin/smart-contract-platform";
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const scpClient = initiateSmartContractPlatformClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.ENTITY_SECRET!,
});

const walletsClient = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.ENTITY_SECRET!,
});

output: two initialized client objects ready for subsequent api calls. store as module-level constants.

step 2: choose deployment path (bytecode vs template vs import)

input: contract source type (custom bytecode, audited template, or existing address).

output: decision (see decision points section).

step 3: deploy from bytecode

input: compiled contract bytecode (prefixed 0x), contract abi (json), constructor parameters (array, types must match abi), alphanumeric contract name, valid uuid v4 idempotency key.

import crypto from 'node:crypto';

const response = await scpClient.deployContract({
  blockchain: 'ARC-TESTNET',
  name: 'MyToken',
  abi: contractABI,
  bytecode: '0x60806040...',
  constructorParameters: [param1, param2],
  idempotencyKey: crypto.randomUUID(),
});

const contractId = response.data?.contractId;

output: contract id string. deployment is asynchronous, proceed to step 5 (polling).

step 4: deploy from template

input: template id (from table above), template parameters object (varies by template, e.g. { name: 'MyToken', symbol: 'MTK', initialSupply: '1000000' }), alphanumeric contract name, valid uuid v4 idempotency key.

const response = await scpClient.deployContract({
  blockchain: 'ARC-TESTNET',
  name: 'MyERC20Token',
  templateId: 'a1b74add-23e0-4712-88d1-6b3009e85a86',
  templateParameters: { name: 'Token', symbol: 'TKN' },
  idempotencyKey: crypto.randomUUID(),
});

const contractId = response.data?.contractId;

output: contract id string. deployment is asynchronous, proceed to step 5 (polling).

step 5: import existing contract

input: target blockchain, contract address on that blockchain, alphanumeric contract name, valid uuid v4 idempotency key.

import crypto from 'node:crypto';

const response = await scpClient.importContract({
  address: '0x123abc...',
  blockchain: 'ARC-TESTNET',
  name: 'ExistingContract',
  idempotencyKey: crypto.randomUUID(),
});

const contractId = response.data?.contractId;

output: contract id string if successful. on duplicate error, proceed to step 5b (fallback).

step 5b: fallback for duplicate import

input: blockchain, contract address (case-insensitive).

const listRes = await scpClient.listContracts({ blockchain: 'ARC-TESTNET' });
const existing = listRes.data?.contracts?.find(c =>
  c.contractAddress.toLowerCase() === '0x123abc...'.toLowerCase()
);
const contractId = existing?.id;

output: contract id string from existing contract. continue with that id.

step 6: poll deployment status (if deployed in step 3 or 4)

input: contract id from step 3 or step 4, target blockchain.

const maxRetries = 60;
let deploymentStatus = null;
let errorReason = null;
let errorDetails = null;

for (let i = 0; i < maxRetries; i++) {
  const res = await scpClient.getContract({ id: contractId, blockchain: 'ARC-TESTNET' });
  const contract = res.data?.contract;
  deploymentStatus = contract?.deploymentStatus;
  errorReason = contract?.deploymentErrorReason;
  errorDetails = contract?.deploymentErrorDetails;

  if (deploymentStatus === 'DEPLOYED' || deploymentStatus === 'FAILED') break;
  await new Promise(r => setTimeout(r, 1000));
}

output: final deployment status (DEPLOYED, FAILED, or PENDING if timeout). if failed, capture errorReason and errorDetails for debugging.

step 7: fetch contract abi and functions

input: contract id (from step 3, 4, or 5).

const contractRes = await scpClient.getContract({ id: contractId, blockchain: 'ARC-TESTNET' });
const contract = contractRes.data?.contract;
const contractAddress = contract?.contractAddress || contract?.address;
const functions = contract?.functions; // array of function objects with name, type, inputs, outputs

output: contract object with address and functions array. each function has name, type (function, constructor, fallback, receive), inputs, and outputs.

step 8a: query a read-only function

input: contract id, function name, function parameters (as array, order matches abi), function signature string (functionName(type1,type2,...)).

const result = await scpClient.queryContract({
  contractId,
  functionSignature: 'balanceOf(address)',
  parameters: ['0xUserAddress'],
  blockchain: 'ARC-TESTNET',
});

const returnValue = result.data?.data; // varies by function

output: function return value (raw bytes or decoded, depending on sdk version). no gas required, no wallet needed.

step 8b: execute a state-changing function

input: contract id, wallet id (with gas funds), function name, function parameters (as array, order matches abi), function signature string, optional fee config, valid uuid v4 idempotency key.

import crypto from 'node:crypto';

const txRes = await walletsClient.createContractExecutionTransaction({
  contractId,
  functionSignature: 'transfer(address,uint256)',
  parameters: ['0xRecipient', '1000000000000000000'],
  walletId: 'wallet-id-from-dcw',
  blockchain: 'ARC-TESTNET',
  fee: { type: 'level', config: { feeLevel: 'MEDIUM' } },
  idempotencyKey: crypto.randomUUID(),
});

const txId = txRes.data?.id;

output: transaction id string. execution is asynchronous, proceed to step 9 (polling).

step 9: poll transaction execution status

input: transaction id from step 8b.

const maxRetries = 60;
let txStatus = null;

for (let i = 0; i < maxRetries; i++) {
  const txRes = await walletsClient.getTransaction({ id: txId });
  txStatus = txRes.data?.transaction?.status;
  
  if (['CONFIRMED', 'COMPLETE', 'FAILED'].includes(txStatus)) break;
  await new Promise(r => setTimeout(r, 1000));
}

output: final transaction status (COMPLETE, CONFIRMED, FAILED, or SENT). if failed, check transaction error details.

step 10: set up event monitoring (webhooks)

input: contract id, event signature string (EventName(type1,type2,...)), webhook url (https, must return 2xx within 30 seconds), optional filters.

import crypto from 'node:crypto';

const webhookRes = await scpClient.createWebhook({
  contractId,
  eventSignature: 'Transfer(address,address,uint256)',
  url: 'https://yourserver.com/webhook/transfer',
  idempotencyKey: crypto.randomUUID(),
});

const webhookId = webhookRes.data?.webhookId;

output: webhook id string. circle will now post event logs to the provided url whenever the event fires on-chain.

step 11: retrieve historical event logs

input: contract id, event signature string, optional block range or filters.

const logsRes = await scpClient.getContractEvents({
  contractId,
  eventSignature: 'Transfer(address,address,uint256)',
  blockchain: 'ARC-TESTNET',
});

const events = logsRes.data?.events; // array of event objects with parameters, txHash, blockNumber

output: array of historical event objects, each with decoded parameters, transaction hash, and block number.

decision points

if deploying a new custom contract: use step 3 (bytecode). compile solidity with evmVersion: "paris" or earlier to avoid the push0 opcode (solidity >= 0.8.20 defaults to shanghai). if solidity >= 0.8.20, explicitly set evmVersion: "paris" in hardhat/foundry config. warn the user that custom bytecode has not been security-audited before deployment.

if deploying a standard token or nft: use step 4 (template) instead of step 3. audited templates (erc-20, erc-721, erc-1155, airdrop) are preferred over custom bytecode. warn the user if they insist on custom bytecode.

if the target contract already exists on-chain: use step 5 (import). if import returns a duplicate/already-exists error, use step 5b (fallback to listContracts and match by address). never fail the flow on import duplicates.

if a function is view or pure (read-only): use step 8a (queryContract). no wallet required, no gas cost. the scp client handles reads.

if a function is nonpayable or payable (state-changing): use step 8b (createContractExecutionTransaction). always use the wallets client, never the scp client. requires wallet id with gas funds.

if targeting mainnet or executing fund transfers: explicitly prompt the user to confirm destination address, amount, network, and token before proceeding. refuse auto-execution. warn if amount exceeds safety threshold (e.g., > 100 usdc).

if idempotency key is not a valid uuid v4: the api will reject with generic "api parameter invalid" error. always use crypto.randomUUID() in node.js. never reuse idempotency keys across different requests.

if deployment or transaction polling times out: assume failure. check error fields in final response. common causes: insufficient gas, invalid bytecode, constructor parameter mismatch, unsupported evm version, or network congestion. retry with adjusted parameters.

if webhook delivery fails repeatedly: check that the receiver url is https, returns 2xx status, and responds within 30 seconds. circle will retry failed webhooks (details in circle docs).

output contract

on successful deployment (step 3 or 4): contract id (string uuid), contract address (string, 0x-prefixed), deployment status (one of PENDING, DEPLOYED, FAILED), contract abi (json array of function objects), on failure: deploymentErrorReason (string, error category) and deploymentErrorDetails (string, specifics).

on successful import (step 5 or 5b): contract id (string uuid), contract address (string, 0x-prefixed), contract abi (json array of function objects).

on successful read query (step 8a): decoded return value (type varies by function). wrapped in result.data.data.

on successful write execution (step 8b): transaction id (string uuid), transaction status (one of INITIATED, SENT, CONFIRMED, COMPLETE, FAILED), on final poll: block number, transaction hash (if confirmed).

on successful webhook creation (step 10): webhook id (string uuid).

on successful event log retrieval (step 11): array of event objects. each event has decoded parameters (object matching event signature types), transaction hash (string, 0x-prefixed), block number (integer), log index (integer).

on failure: error object with code (string) and message (string). common codes: INVALID_PARAMETER (malformed input), UNAUTHORIZED (bad api key), NOT_FOUND (contract id does not exist), DUPLICATE (import address already registered), ESTIMATION_ERROR (deployment failed, check evm version).

outcome signal

• deployment success: getContract() returns deploymentStatus DEPLOYED, contract address is set and non-null.
• import success: importContract() returns contractId, subsequent getContract() call retrieves abi and functions.
• read query success: queryContract() returns decoded data matching function return type (e.g., uint256 for balanceOf).
• write execution success: createContractExecutionTransaction() returns transaction id, final polling shows status CONFIRMED or COMPLETE, transaction is visible on block explorer.
• webhook setup success: createWebhook() returns webhookId, incoming http posts from circle appear on your receiver url.
• event log retrieval success: getContractEvents() returns non-empty array of events with decoded parameters matching event signature.

the user sees confirmation via console logs, api responses, and eventually on-chain visibility (block explorer for deployments/txs, blockchain logs for events).

---

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.