Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kwala.network/docs/llms.txt

Use this file to discover all available pages before exploring further.

Actions are the core building blocks of Kwala workflows. They define what your workflow actually does. This could be deploying smart contracts, calling contract functions, sending tokens, or invoking external APIs. Each workflow can contain multiple actions that are executed either sequentially or in parallel.

​
Action types

Kwala supports three primary action types:
  • Deploy: Deploy new smart contracts to blockchain networks
  • Call: Interact with existing smart contracts
  • API: Invoke external Web2 APIs

​
Deploy actions

Deploy actions are used to deploy new smart contracts to a blockchain network. You can also use deploy actions to deploy Kwala Functions, which enable custom on-chain decision logic. In the following example, we deploy an NFT contract to Ethereum mainnet. The initialization parameters are contract name (“MyNFT”), symbol (“NFT”), and initial supply (1000 tokens). 
actions:
  - name: "Deploy NFT Contract"
    type: "deploy"
    bytecode: "0x60806040523480156200001157600080fd5b50..."
    encodedABI: "0x..."
    initializationArgs:
      - "MyNFT"
      - "NFT"
      - "1000"
    chainID: 1
    metadata: "NFT deployment on Ethereum mainnet"
    retriesUntilSuccess: 3
Required fields for deploy:
FieldDescription
nameUnique identifier for this action
typeMust be "deploy"
bytecodeThe compiled contract bytecode (hex string)
encodedABIABI-encoded constructor parameters
initializationArgsArray of constructor arguments
chainIDTarget blockchain network ID
Optional fields:
FieldDescriptionDefault
metadataAdditional information about the deployment-
retriesUntilSuccessNumber of retry attempts on failure0

​
Call actions

Call actions interact with already deployed smart contracts by calling their functions. The following example calls the transfer function on an ERC-20 token contract to send 1 token to a recipient address: 
actions:
  - name: "Transfer Tokens"
    type: "call"
    targetContract: "0x742d35Cc6e9A5f1e7A0e6FD4C8b2Bc3F5d9E1234"
    targetFunction: "transfer"
    targetParams:
      - "0xRecipientAddress..."
      - "1000000000000000000"  # 1 token with 18 decimals
    chainID: 1
    encodedABI: "0xa9059cbb..."
    metadata: "Token transfer to user"
    retriesUntilSuccess: 2
Required fields for call:
FieldDescription
nameUnique identifier for this action
typeMust be "call"
targetContractAddress of the smart contract to interact with
targetFunctionName of the function to call (For example, transfer, mint)
targetParamsArray of parameters for the function call
chainIDTarget blockchain network ID
encodedABIABI-encoded function call
Optional fields:
FieldDescriptionDefault
metadataAdditional information about the call-
retriesUntilSuccessNumber of retry attempts on failure0

​
API actions

API actions allow you to integrate Web2 services into your Web3 workflows. The following example action sends a Discord notification using a webhook to announce that a new NFT has been minted, including an embedded message with the token ID. 
actions:
  - name: "Send Discord Notification"
    type: "api"
    APIEndpoint: "https://discord.com/api/webhooks/your-webhook"
    APIPayload:
      content: "New NFT minted!"
      embeds:
        - title: "NFT Minted"
          description: "Token ID #1234"
          color: 3447003
    metadata: "Discord webhook notification"
    retriesUntilSuccess: 1
Required fields for API:
FieldDescription
nameUnique identifier for this action
typeMust be "api"
APIEndpointFull URL of the API endpoint
APIPayloadRequest body/parameters for the API call
Optional fields:
FieldDescriptionDefault
metadataAdditional information about the API call-
retriesUntilSuccessNumber of retry attempts on failure0

​
Complete field reference

Here’s a comprehensive reference of all action fields:
FieldRequiredUsed InDescription
NameRequiredAllUnique name for this action
TypeRequiredAllType of action: deploy, call, or api
APIEndpointRequired for apiAPIURL if making an API call
APIPayloadRequired for apiAPIRequest body for the API call
BytecodeRequired for deployDeployContract bytecode (hex string) when deploying
EncodedABIRequiredDeploy, CallABI-encoded constructor or function call
InitializationArgsRequired for deployDeployArguments to pass into the constructor
TargetContractRequired for callCallAddress of the smart contract to interact with
TargetFunctionRequired for callCallFunction name such as transfer, mint, or others.
TargetParamsRequired for callCallParameters for the function call
ChainIDRequiredDeploy, CallEVM Chain ID where the action will be executed
MetadataOptionalAllOptional metadata or tags
RetriesUntilSuccessOptionalAllNumber of retries until success (default is 0)

​
Retry logic

The retriesUntilSuccess field allows actions to automatically retry on failure. The following example configures a critical contract call to automatically retry up to 5 times if it fails, ensuring higher reliability for important operations. 
actions:
  - name: "Critical Contract Call"
    type: "call"
    retriesUntilSuccess: 5  # Will retry up to 5 times
    # ... other config
Each retry attempt consumes credits. Use retries carefully and consider setting appropriate limits. Retry behavior:
  • Retries happen automatically on failure
  • A delay is applied between retries
  • Total attempts = 1 (initial) + retriesUntilSuccess
  • Failed retries still consume credits

​
Best practices for workflow actions

  • Use descriptive action names - Choose clear, descriptive names that explain what each action does. It’s easier to understand and debug a workflow called Deploy NFT Marketplace Contract as opposed to Action1.
  • Validate parameters - Double-check all parameters, especially addresses and amounts, before deploying workflows
  • Set appropriate retries - Use retries for critical operations, but avoid excessive retries that waste credits
    • Network calls: 2-3 retries
    • Contract deployments: 1-2 retries
    • Simple reads: 0-1 retries
  • Add metadata - Use the metadata field to document why an action exists and any important context
  • Test in the Playground - Always test your actions in the Kwala Playground before deploying to production

​
Combining Web2 and Web3 actions

One of Kwala’s key features is the ability to combine Web2 and Web3 actions in a single workflow. The following example demonstrates a complete workflow that mints an NFT on-chain, sends an email notification to the user via SendGrid API, and logs the transaction to a database via a custom API endpoint. 
name: "NFT Mint with Notification"
execution: sequential

actions:
  # Web3 Action
  - name: "Mint NFT"
    type: "call"
    targetContract: "0x..."
    targetFunction: "mint"
    targetParams:
      - "0xUserAddress..."
    chainID: 1

  # Web2 Action
  - name: "Send Email Notification"
    type: "api"
    APIEndpoint: "https://api.sendgrid.com/v3/mail/send"
    APIPayload:
      personalizations:
        - to:
            - email: "user@example.com"
      subject: "Your NFT has been minted!"
      content:
        - type: "text/plain"
          value: "Congratulations! Your NFT is ready."

  # Another Web2 Action
  - name: "Log to Database"
    type: "api"
    APIEndpoint: "https://api.example.com/logs"
    APIPayload:
      action: "nft_minted"
      user: "0xUserAddress..."
      timestamp: "{{now}}"

​
Next steps

Working with Triggers

Learn how to trigger your workflows

Workflow Execution

Understand workflow execution modes

YAML Basics

Master Kwala’s YAML syntax

Use Cases

Explore real-world examples