AI Agent Integration

ForgingBlock enables AI agents to create and execute crypto payments autonomously.

Agents can interact with the ForgingBlock payment infrastructure to:

• create payment orders
• resolve checkout links into blockchain transactions
• execute payments
• verify payment completion

A full working example is available:

ForgingBlock AI Payment Agent

This example demonstrates how an AI agent can orchestrate the complete payment lifecycle.

---

Agent Roles

ForgingBlock supports two types of AI agents.

Payment Agent

A payment agent can pay a checkout.

This does not require an API key.

The agent can:

• resolve a checkout link
• retrieve blockchain payment instructions
• execute the transaction
• verify payment status

This enables AI assistants and automated bots to perform payments safely.

Merchant Agent

A merchant agent can create payment orders.

This requires a merchant API key.

Dashboard → Account Settings → Integrations → API Token

Example capability:

create_order

Typical usage:

Create an order for Coffee for $2

The agent returns a checkout link which can be shared with customers.

---

Architecture

User / AI Agent
        │
        ▼
AI Agent Runtime
(LLM / Agent Framework)
        │
        ▼
ForgingBlock Payment API
        │
        ▼
Blockchain Network
(Base / EVM networks)

The agent retrieves deterministic payment instructions and executes them using a wallet provider.

---

Agent Payment Flow

A typical AI-driven payment flow consists of four steps.

⚠️

Important: Agents must NOT construct transactions manually.
Always use recommendedTx returned by the API.

---

1. Merchant Creates an Order

A merchant agent creates a payment order.

Note: Pass that step if you interested only in payment agent

Example request:

Create an order for Coffee for $2

The agent calls:

create_order

Example parameters:

price_amount: 2
price_currency: USD
title: "Coffee"
description: "Coffee for $2"

The action returns:

checkout_url
checkout_id
invoice_url
order_id

Example checkout link:

https://api.forgingblock.io/api/v1/checkout?id=...

The merchant shares this link with a customer or payment agent.

---

2. Agent Resolves Checkout

A payment agent receives the checkout link.

Example user request:

Pay this checkout
https://api.forgingblock.io/api/v1/checkout?id=...

The agent calls:

create_payment

The action returns deterministic blockchain payment instructions:

invoiceId
invoiceUrl
network
token
amount
recommendedTx
verifyUrl

⚠️

recommendedTx is the only correct way to execute the payment.
Do NOT extract wallet addresses or build transactions manually.

Amount & Token Format

amount: { decimal, atomic }
token:  { symbol, address, decimals }

Use:

• decimal → display
• atomic → blockchain execution

---

3. Agent Executes the Transaction

After the user confirms the payment, the agent executes the transaction using its wallet provider.

Example execution:

wallet_sendTransaction(recommendedTx)

Required Fields

The API provides:

• to
• data
• value
• gas
• chainId

The agent must add:

• from
• nonce
• gasPrice

Example:

tx = {
  ...recommendedTx,
  from: wallet.address,
  nonce: getTransactionCount(wallet.address),
  gasPrice: getGasPrice()
}

Important rules:

• ERC-20 transfers are encoded in the transaction data
• the token contract address is in tx.to
• value remains 0x0
• the agent must not recompute token transfers manually

The transaction must be executed exactly as returned.

---

4. Agent Verifies Payment

After submitting the transaction, the agent verifies payment status.

The agent calls:

verify_payment

Possible statuses:

new
partially_paid
completed
expired

A payment is considered successful when:

status = completed

---

⚠️ Do NOT Use watchers

The watchers field in order responses does NOT contain payment instructions and is often empty.

❌ Do NOT:

• read payment address from watchers
• rely on watchers for execution

✅ Always use:

/pay/resolve

This is the only supported way to obtain payment details.

Summary

ForgingBlock enables AI-native payment workflows where agents can:

• create payment orders (merchant agents)
• resolve checkout links
• execute blockchain payments
• verify payment completion