Skip to content

docs: add scheduling transactions details and examples in Hedera tools guide #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
piotrswierzy merged 1 commit into from
Jan 13, 2026
Merged

docs: add scheduling transactions details and examples in Hedera tools guide #169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions docs/HEDERAPLUGINS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,3 +251,75 @@ The Python SDK currently supports one agent mode:

> **Coming Soon:** `AgentMode.RETURN_BYTES` - In this mode, the agent creates the transaction and returns the bytes for
> the user to execute in another tool (human-in-the-loop pattern).

---

## Scheduling Transactions

Most tools in the Hedera Agent Kit support **scheduled transactions**. This allows you to create a transaction that will be executed at a later time or once specific signatures are collected.

### Scheduling Parameters

When a tool supports scheduling, it accepts an optional `schedulingParams` object with the following fields:

| Field | Type | Description |
|---|---|---|
| `is_scheduled` | `boolean` | Set to `true` to create a scheduled transaction instead of executing immediately. |
| `expiration_time` | `string` | ISO 8601 formatted date string (e.g., "2026-02-01T00:00:00Z") when the transaction expires if not fully signed. |
| `wait_for_expiry` | `boolean` | If `true`, the transaction executes only at `expiration_time`. If `false` (default), it executes as soon as signatures are collected. |
| `admin_key` | `boolean \| string` | Admin key to manage the scheduled transaction. `true` uses the operator key. |
| `payer_account_id` | `string` | Account ID that pays the execution fee. Defaults to the operator. |

### Supported Tools

The following tools currently support transaction scheduling:

**Core Account Plugin**
* `CREATE_ACCOUNT_TOOL`
* `UPDATE_ACCOUNT_TOOL`
* `TRANSFER_HBAR_TOOL`

**Core Token Plugin**
* `CREATE_FUNGIBLE_TOKEN_TOOL`
* `CREATE_NON_FUNGIBLE_TOKEN_TOOL`
* `MINT_FUNGIBLE_TOKEN_TOOL`
* `MINT_NON_FUNGIBLE_TOKEN_TOOL`
* `TRANSFER_NON_FUNGIBLE_TOKEN_TOOL`
* `TRANSFER_NFT_WITH_ALLOWANCE_TOOL`
* `TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL`
* `AIRDROP_FUNGIBLE_TOKEN_TOOL`
* `DISSOCIATE_TOKEN_TOOL`
* `DELETE_NON_FUNGIBLE_TOKEN_ALLOWANCE_TOOL`

**Core Consensus Plugin**
* `SUBMIT_TOPIC_MESSAGE_TOOL`

**Core EVM Plugin**
* `CREATE_ERC20_TOOL`
* `TRANSFER_ERC20_TOOL`
* `CREATE_ERC721_TOOL`
* `MINT_ERC721_TOOL`
* `TRANSFER_ERC721_TOOL`

### Prompting Best Practices

To successfully create a scheduled transaction via an AI agent, use clear and explicit prompts:

1. **Explicit Intent**: clearly state that you want to *schedule* the transaction.
2. **Specific Timestamps**: Use exact dates for expiration or execution time. Avoid relative terms like "tomorrow" or "in 2 days" if possible, or ensure the agent can resolve them to a specific date.

**Good Examples:**
* "Transfer 10 HBAR to 0.0.12345 and schedule it to expire on 2025-12-31."
* "Create a scheduled transaction to mint 100 tokens of 0.0.56789, executing on 2026-01-01."

**Bad Examples:**
* "Transfer 10 HBAR later." (Vague timing)
* "Schedule a transfer." (Missing expiration details might default unexpectedly)

### Python SDK Implementation

In the Python SDK, scheduling is handled via the `OptionalScheduledTransactionParams` schema in `hedera_agent_kit.shared.parameter_schemas.common_schema`. Tools inheriting from this schema automatically support the parameters listed above.

To enable scheduling in a custom tool:
1. Inherit from `OptionalScheduledTransactionParams`.
2. In your tool's logic, use `HederaBuilder.maybe_wrap_in_schedule` to conditionally wrap the transaction.
23 changes: 21 additions & 2 deletions docs/HEDERATOOLS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Transfer HBAR between accounts.
Transfer 0.1 HBAR to 0.0.12345
Transfer 0.05 HBAR to 0.0.12345 with memo "Payment for services"
Can you move 0.05 HBARs to account with ID 0.0.12345?
Transfer 1 HBAR to 0.0.12345 and schedule the transaction with expiration time 01.02.2026
```

---
Expand All @@ -106,6 +107,7 @@ Creates a new Hedera account.
Create a new Hedera account
Create a new account with 10 HBAR
Create an account with memo "My primary account" and 5 HBAR initial balance
Create a new account with 10 HBAR and schedule the transaction with expiration time 01.02.2026
```

---
Expand All @@ -129,6 +131,7 @@ Update an account's metadata.
```
Update account 0.0.12345 to have max auto associations of 10
Set my account memo to "Updated account"
Set my account memo to "Scheduled Update" and schedule this with expiration time 01.02.2026
```

---
Expand Down Expand Up @@ -404,6 +407,7 @@ Submit a message to an HCS topic.
```
Submit "Hello World" to topic 0.0.12345
Post a message "Daily update" to topic 0.0.12345
Submit "Scheduled Message" to topic 0.0.12345 and schedule with expiration time 01.02.2026
```

---
Expand Down Expand Up @@ -524,7 +528,7 @@ Create a fungible token on Hedera.
```
Create a fungible token named MyToken with symbol MTK
Create a fungible token GoldCoin with symbol GLD, initial supply 1000, decimals 2, finite supply with max supply 5000
Create a fungible token named MyToken with symbol MTK. Schedule the transaction instead of executing it immediately.
Create a fungible token named MyToken with symbol MTK. Schedule the transaction with expiration 01.02.2026.
```

---
Expand All @@ -548,6 +552,7 @@ Create a non-fungible token (NFT) on Hedera.
```
Create an NFT collection named MyNFT with symbol MNFT
Create an NFT named ArtCollection with symbol ART and max supply 1000
Create an NFT collection named ScheduledNFT and schedule with expiration 01.02.2026
```

---
Expand All @@ -568,6 +573,7 @@ Mint additional supply of a fungible token.
```
Mint 100 tokens of 0.0.12345
Add 500 supply to token 0.0.12345
Mint 100 tokens of 0.0.12345 and schedule with expiration 01.02.2026
```

---
Expand All @@ -588,6 +594,7 @@ Mint NFTs with metadata.
```
Mint NFT 0.0.12345 with metadata ipfs://QmTest123
Mint 3 NFTs for token 0.0.12345 with URIs ["ipfs://a", "ipfs://b", "ipfs://c"]
Mint NFT 0.0.12345 with metadata ipfs://Scheduled and schedule with expiration 01.02.2026
```

---
Expand All @@ -608,6 +615,7 @@ Associate tokens with an account.
```
Associate token 0.0.12345 with my account
Associate tokens 0.0.12345 and 0.0.67890 with account 0.0.11111
Associate token 0.0.12345 with my account and schedule with expiration 01.02.2026
```

---
Expand All @@ -629,6 +637,7 @@ Dissociate tokens from an account.
```
Dissociate token 0.0.12345 from my account
Remove token 0.0.12345 association from account 0.0.67890
Dissociate token 0.0.12345 from my account and schedule with expiration 01.02.2026
```

---
Expand All @@ -651,6 +660,7 @@ Airdrop fungible tokens to multiple recipients.
```
Airdrop 100 tokens of 0.0.12345 to accounts 0.0.11111 and 0.0.22222
Send 50 tokens each of 0.0.12345 to three accounts
Airdrop 100 tokens of 0.0.12345 to 0.0.11111 and schedule with expiration 01.02.2026
```

---
Expand All @@ -673,6 +683,7 @@ Transfer fungible tokens using an allowance.
```
Transfer 50 tokens of 0.0.12345 from 0.0.11111 to 0.0.22222 using allowance
Use my token allowance to send 100 tokens from 0.0.11111
Transfer 50 tokens of 0.0.12345 from 0.0.11111 using allowance and schedule with expiration 01.02.2026
```

---
Expand All @@ -695,6 +706,7 @@ Transfer NFTs using an allowance.
```
Transfer NFT 0.0.12345 serial 1 from 0.0.11111 to 0.0.22222 using allowance
Use allowance to send NFT serial 5 from owner 0.0.11111
Transfer NFT 0.0.12345 serial 1 from 0.0.11111 using allowance and schedule with expiration 01.02.2026
```

---
Expand All @@ -717,6 +729,7 @@ Delete fungible token allowances.
```
Delete token allowance for token 0.0.12345 from spender 0.0.67890
Remove all token allowances for spender 0.0.67890
Delete token allowance for token 0.0.12345 from spender 0.0.67890 and schedule with expiration 01.02.2026
```

---
Expand All @@ -740,6 +753,7 @@ token.
```
Delete NFT allowance for token 0.0.12345 serials [1, 2]
Remove NFT allowance for token 0.0.67890 serial 5
Delete NFT allowance for token 0.0.12345 serials [1] and schedule with expiration 01.02.2026
```

---
Expand All @@ -763,6 +777,7 @@ a single transaction.
```
Transfer NFT 0.0.12345 serial 1 to 0.0.67890
Send NFT 0.0.12345 serial 2 from 0.0.11111 to 0.0.22222
Transfer NFT 0.0.12345 serial 1 to 0.0.67890 and schedule with expiration 01.02.2026
```

---
Expand Down Expand Up @@ -827,7 +842,7 @@ Deploy an ERC-20 token via factory contract.
```
Create an ERC20 token named MyERC20 with symbol M20
Create an ERC20 token GoldToken with symbol GLD, decimals 2, initial supply 1000
Create an ERC20 token named "MyToken" with symbol MTK. Schedule this transaction instead of executing it immediately.
Create an ERC20 token named "MyToken" with symbol MTK. Schedule with expiration 01.02.2026.
```

---
Expand All @@ -853,6 +868,7 @@ Transfer ERC-20 tokens.
```
Transfer 100 tokens of contract 0.0.12345 to 0.0.67890
Send 50 ERC20 tokens from 0x1234... to 0x5678...
Transfer 100 tokens of 0.0.12345 to 0.0.67890 and schedule with expiration 01.02.2026
```

---
Expand All @@ -874,6 +890,7 @@ Deploy an ERC-721 (NFT) token via factory contract.
```
Create an ERC721 token named MyNFT with symbol MNFT
Create an ERC721 collection called ArtDrops with symbol AD and base URI ipfs://Qm...
Create an ERC721 token named MyNFT with symbol MNFT and schedule with expiration 01.02.2026
```

---
Expand All @@ -895,6 +912,7 @@ Mint a new ERC-721 NFT by calling the `safeMint(to)` function on the contract.
Mint ERC721 token 0.0.6486793 to 0xd94dc7f82f103757f715514e4a37186be6e4580b
Mint ERC721 token 0.0.6486793 to Hedera account ID 0.0.2222222
Mint ERC721 token 0.0.9999
Mint ERC721 token 0.0.9999 and schedule with expiration 01.02.2026
```

---
Expand All @@ -921,6 +939,7 @@ Transfer an ERC-721 NFT.
```
Transfer ERC721 token 0 from contract 0.0.12345 to 0.0.67890
Send NFT #5 from 0x1234... to 0x5678...
Transfer ERC721 token 0 from contract 0.0.12345 to 0.0.67890 and schedule with expiration 01.02.2026
```

---
Expand Down