> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# EVM Onchain Actions

Build EVM workflows that read chain data, evaluate policy, and execute wallet-backed transactions.

EVM actions let workflows read chain state and execute wallet-backed transactions. Use them for token transfers, contract calls, approvals, swaps, position management, and policy-driven automations.

**Gasless Stablecoin Swaps Inside B3OS, Powered by Relay**

## Common EVM Workflow

graph TD
    Trigger[Trigger] --> Read[Read chain or market data]
    Read --> Policy[Policy branch]
    Policy -->|Allowed| Simulate[Optional simulation]
    Simulate --> Tx[Wallet-backed transaction]
    Policy -->|Blocked| Notify[Notify or log]
    Tx --> Record[Record result]

## Design Rules

| Rule                    | Why                                                                       |
| ----------------------- | ------------------------------------------------------------------------- |
| Read before write       | Chain state can change and provider inputs need validation                |
| Validate addresses      | Wrong-chain or malformed addresses can fail or send funds incorrectly     |
| Check balances          | Gas token and asset balances affect transaction success                   |
| Use policy branches     | Prevent unintended transactions from noisy triggers or malformed payloads |
| Keep approvals narrow   | Broad approvals increase risk                                             |
| Record transaction hash | Downstream systems need traceability                                      |

## Inputs to Validate

| Input          | Examples                                              |
| -------------- | ----------------------------------------------------- |
| Chain          | Base, Ethereum, or another supported EVM chain        |
| Token          | Contract address, symbol, decimals, native token flag |
| Amount         | Raw units or token units, slippage, minimum output    |
| Recipient      | Address, contract, treasury, protocol address         |
| ABI and method | Function name, argument types, payable value          |
| Wallet         | Organization wallet and execution permissions         |

## Session Keys and Nonces

Some EVM workflows use session-key or delegated execution patterns. B3OS also coordinates nonce-sensitive wallet execution to reduce conflicts between concurrent transactions.

**Concurrency matters**

Avoid publishing multiple high-frequency workflows that spend from the same wallet without understanding nonce, gas,
  and balance behavior.

## Failure Modes

| Failure                  | Typical cause                                                             |
| ------------------------ | ------------------------------------------------------------------------- |
| Schema validation failed | Missing chain, wallet, address, token, or amount field                    |
| Simulation failed        | Contract would revert, insufficient balance, or invalid calldata          |
| Transaction reverted     | Chain state changed, slippage, allowance, deadline, or contract condition |
| Nonce conflict           | Concurrent transaction activity                                           |
| Provider error           | RPC, rate limit, unsupported chain, or malformed request                  |

## Related Docs

**[Wallets](/platform/wallets)**

Organization wallet model and transaction safety.
  **[Security](/platform/security)**

Workflow, API key, connector, webhook, and wallet protections.
  **[Expressions](/platform/expressions)**

Pass trigger and read-action data into transaction payloads.