Get Started

Once you have Engine set up, learn the basics of Engine.

Blockchain read calls (e.g. get token balance) are synchronous and will return the value read.

Blockchain write calls (e.g. transfer tokens) are asynchronous:

• Your app backend sends a write transaction to Engine.
• Engine enqueues the job and returns a reference to the job: queueId.
  • If queueId is returned, this transaction will be attempted.
  • If queueId is not returned, this transaction failed to be added to the queue and will not be attempted.
• Engine will attempt to submit the transaction from your specified backend wallet.
  • If there is an error (failed simulation, out of gas), the transaction is set to errored and will not be re-attempted.
• Engine polls to check if the transaction is mined. If it is, the transaction is set to mined.
• If the transaction is not mined after some duration, Engine re-submits the transaction with aggressive gas settings. This transaction is sent with the same nonce and will be mined at most once.

• Queued: The transaction was received by Engine and waiting in the transaction queue.
• Sent: The transaction was successfully sent to RPC.
• Mined: The transaction was successfully mined onchain.
• Cancelled: The transaction was cancelled by the user.
• Errored: The transaction failed to be sent to RPC or to the chain's nodes. This can happen for many reasons (malformed transaction, failed simulation, too low gas).

Navigate to the thirdweb Engine dashboard to manage your Engine instances.

Overview

• View your backend wallets.
• Create a backend wallet.
• View recent transactions.
• View transaction details (e.g. error messages, gas used).
• Cancel a queued transaction.

Explorer

• Interactively view and call your Engine API.

Relayer

• View relayers.
• Add or remove relayers.

Configuration

• Change backend wallet types.
• View webhooks.
• Add and remove webhooks.

Permissions

• View admin users.
• Add and remove admin users.
• View access tokens.
• Create and revoke access tokens.

Engine endpoints require authentication.

• Add other admins for other users to manage Engine from the dashboard.
• Create access tokens for your backends to call the Engine API. These are secrets that should be stored securely.
• Revoke permissions at any time.

Learn more about admins and access tokens.

Backend wallet are your wallets managed by Engine. Engine will send blockchain transactions from these wallets.

• Configure how to back up wallets.
• Create or import a backend wallet.
• Specify the backend wallet to use when calling the Engine API.

Learn more about backend wallets.

Here are a few example API calls.

const resp = await fetch(
  "<engine_url>/backend-wallet/<chain>/<backend_wallet_address>/get-balance",
  {
    headers: {
      Authorization: "Bearer <access_token>",
    },
  },
);
 
const { result } = await resp.json();
console.log("Balance:", result.value);

This code example does not require gas funds and returns the function result.

const resp = await fetch(
  "<engine_url>/contract/<chain>/<contract_address>/read?functionName=balanceOf&args=0x3EcDBF3B911d0e9052b64850693888b008e18373",
  {
    headers: {
      Authorization: "Bearer <access_token>",
    },
  },
);
 
const { result } = await resp.json();
console.log("ERC-20 balance:", result);

This code example calls a write method on a contract. It requires gas funds and returns a queueId to query for the result.

const resp = await fetch(
  "<engine_url>/contract/<chain>/<contract_address>/write",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <access_token>",
      "x-backend-wallet-address": "<backend_wallet_address>",
    },
    body: JSON.stringify({
      functionName: "transferFrom",
      args: [
        "0x1946267d81Fb8aDeeEa28e6B98bcD446c8248473",
        "0x3EcDBF3B911d0e9052b64850693888b008e18373",
        "0",
      ],
    }),
  },
);
 
const { result } = await resp.json();
// queueId is a reference to the transaction queued by Engine.
console.log("Queue ID:", result.queueId);

This code example deploys a thirdweb NFT drop contract. It requires gas funds and returns a queueId to query for the result.

const resp = await fetch(
  "<engine_url>/deploy/<chain>/prebuilts/nft-drop",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <access_token>",
      "x-backend-wallet-address": "<backend_wallet_address>",
    },
    body: JSON.stringify({
      contractMetadata: {
        name: "thirdweb Engine example",
        symbol: "eng",
        primary_sale_recipient:
          "0x3EcDBF3B911d0e9052b64850693888b008e18373",
      },
    }),
  },
);
 
const { result } = await resp.json();
// queueId is a reference to the transaction queued by Engine.
console.log("Queue ID:", result.queueId);

Engine can enable your application to airdrop NFTs, send funds between wallets, update onchain game state, and more.

const resp = await fetch(
  "<engine_url>/transaction/status/<queue_id>",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer <access_token>",
    },
  },
);
 
const { result } = await resp.json();
// status can be: processed, queued, sent, errored, mined, cancelled, retried
const isComplete = ["mined", "errored", "cancelled"].includes(
  result.status,
);

Get notified when a transaction is mined, in addition to other wallet and transaction events.

• Navigate to the Webhooks tab on the Engine dashboard.
• Create a new webhook URL.

Learn more about webhooks.