llamaIndex - ✅(Solved) Fix Feature: agentpay-mcp — payment tool for LlamaIndex agents (x402, human-approval, spend caps) [1 pull requests, 1 participants]

up2itnow0822 · 2026-03-29T18:39:01Z

[llamaIndex] PR 17: feat: x402 payment tool — enable agents to pay for premium APIs - Repository: NVIDIA/NeMo-Agent-Toolkit-Examples - Author: up2itnow0822 - S… # PR #17: feat: x402 payment tool — enable agents to pay for premium APIs - Repository: NVIDIA/NeMo-Agent-Toolkit-Examples - Author: up2itnow0822 - State: closed | merged: True - Link: https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17 ## Description (problem / solution / changelog) ## Summary Adds a community-contributed example demonstrating how to build a **payment-enabled tool** for NeMo Agent Toolkit using the [x402 protocol](https://github.com/coinbase/x402) (HTTP 402 machine-to-machine payments). Related issue: NVIDIA/NeMo-Agent-Toolkit#1806 ## What This Example Does When an agent calls a paid API and receives an HTTP 402 response, this tool: 1. Parses the x402 payment requirements from the 402 response 2. Evaluates the cost against a configurable spending policy (per-transaction caps, daily limits, recipient allowlists) 3. Signs a payment proof using the agent's wallet (key isolated from agent context) 4. Retries the request with the payment proof attached ## Files ``` examples/x402_payment_tool/ ├── README.md # Overview, architecture, quick start ├── pyproject.toml # Package config with nat.components entry point ├── scripts/ │ └── mock_paid_api.py # Mock API server for testing (no real payments) └── src/nat_x402_payment/ ├── __init__.py ├── register.py # NeMo Agent Toolkit component registration ├── payment_tool.py # Main tool: PaidAPITool with 402 handling ├── spending_policy.py # Spending limits enforcement ├── x402.py # x402 protocol parser and payment signer └── configs/ └── payment-agent.yml.example # Example agent configuration ``` ## Security Architecture | Concern | Mitigation | |---------|-----------| | Agent overspending | Per-transaction and daily caps enforced BEFORE signing | | Key leakage | Wallet key isolated in signing function; never enters LLM context | | Wrong recipient | Configurable recipient allowlist | | Replay attacks | x402 nonce and expiry in payment proofs | ## Why Payment Tools Are Different As discussed in NVIDIA/NeMo-Agent-Toolkit#1806, payment operations have unique security requirements compared to regular API tools: - **Irreversible** — misdirected payments cannot be recovered - **Key sensitivity** — private keys can't be rotated like API keys - **Authorization scope** — the agent needs enforceable spending limits that the LLM cannot override - **Decision loop** — the agent must evaluate cost vs. value before paying ## Testing The example includes a mock paid API server (`scripts/mock_paid_api.py`) that simulates the full 402 → payment → 200 flow without any real blockchain transactions. Set `payment.mock: true` in the config. ## Changed files - `ci/vale/styles/config/vocabularies/nemo-agent-toolkit-examples/accept.txt` (modified, +3/-0) - `examples/x402_payment_tool/.gitignore` (added, +3/-0) - `examples/x402_payment_tool/README.md` (added, +209/-0) - `examples/x402_payment_tool/pyproject.toml` (added, +41/-0) - `examples/x402_payment_tool/scripts/mock_x402_server.py` (added, +133/-0) - `examples/x402_payment_tool/src/nat_x402_payment/__init__.py` (added, +14/-0) - `examples/x402_payment_tool/src/nat_x402_payment/configs/payment-agent.example.yml` (added, +52/-0) - `examples/x402_payment_tool/src/nat_x402_payment/register.py` (added, +376/-0) - `examples/x402_payment_tool/src/nat_x402_payment/wallet.py` (added, +219/-0) ## Fix / Workaround agentpay-mcp is an open-source MCP server that gives agents a `pay` tool for the [x402 protocol](https://github.com/coinbase/x402) (HTTP 402 Payment Required). It's MIT licensed, has 149 tests passing, and was recently merged into NVIDIA's NeMo-Agent-Toolkit-Examples: https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17 ## What's missing LlamaIndex agents can call APIs, query databases, and orchestrate complex workflows — but there's no standard way for them to handle payments. If your agent needs to call a paid API, trigger an invoice, or make a micropayment mid-workflow, you're writing custom code from scratch every time. ## The proposal Add [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) as a supported MCP tool in LlamaIndex's tool integrations. agentpay-mcp is an open-source MCP server that gives agents a `pay` tool for the [x402 protocol](https://github.com/coinbase/x402) (HTTP 402 Payment Required). It's MIT licensed, has 149 tests passing, and was recently merged into NVIDIA's NeMo-Agent-Toolkit-Examples: https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17 Key behaviors: - **Human-approval mode**: agent requests payment, human approves before funds move - **On-chain spend caps**: hard limits enforced by smart contract, not just config - **Audit trail**: every payment logged with agent ID, tool call, amount, timestamp - **Non-custodial**: you hold your own keys ## What it looks like in practice ```python from llama_index.t

llamaIndex2026-03-29 18:39:01

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

run-llama/llama_index#21214•Fetched 2026-04-08 01:48:45

View on GitHub

Comments

Participants

Timeline

Reactions

Author

up2itnow0822

Participants

up2itnow0822

Timeline (top)

closed ×1

Fix Action

Fix / Workaround

agentpay-mcp is an open-source MCP server that gives agents a pay tool for the x402 protocol (HTTP 402 Payment Required). It's MIT licensed, has 149 tests passing, and was recently merged into NVIDIA's NeMo-Agent-Toolkit-Examples: https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17

PR fix notes

PR #17: feat: x402 payment tool — enable agents to pay for premium APIs

Repository: NVIDIA/NeMo-Agent-Toolkit-Examples
Author: up2itnow0822
State: closed | merged: True
Link: https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17

Description (problem / solution / changelog)

Summary

Adds a community-contributed example demonstrating how to build a payment-enabled tool for NeMo Agent Toolkit using the x402 protocol (HTTP 402 machine-to-machine payments).

Related issue: NVIDIA/NeMo-Agent-Toolkit#1806

What This Example Does

When an agent calls a paid API and receives an HTTP 402 response, this tool:

Parses the x402 payment requirements from the 402 response
Evaluates the cost against a configurable spending policy (per-transaction caps, daily limits, recipient allowlists)
Signs a payment proof using the agent's wallet (key isolated from agent context)
Retries the request with the payment proof attached

Files

examples/x402_payment_tool/
├── README.md                           # Overview, architecture, quick start
├── pyproject.toml                      # Package config with nat.components entry point
├── scripts/
│   └── mock_paid_api.py               # Mock API server for testing (no real payments)
└── src/nat_x402_payment/
    ├── __init__.py
    ├── register.py                    # NeMo Agent Toolkit component registration
    ├── payment_tool.py                # Main tool: PaidAPITool with 402 handling
    ├── spending_policy.py             # Spending limits enforcement
    ├── x402.py                        # x402 protocol parser and payment signer
    └── configs/
        └── payment-agent.yml.example  # Example agent configuration

Security Architecture

Concern	Mitigation
Agent overspending	Per-transaction and daily caps enforced BEFORE signing
Key leakage	Wallet key isolated in signing function; never enters LLM context
Wrong recipient	Configurable recipient allowlist
Replay attacks	x402 nonce and expiry in payment proofs

Why Payment Tools Are Different

As discussed in NVIDIA/NeMo-Agent-Toolkit#1806, payment operations have unique security requirements compared to regular API tools:

Irreversible — misdirected payments cannot be recovered
Key sensitivity — private keys can't be rotated like API keys
Authorization scope — the agent needs enforceable spending limits that the LLM cannot override
Decision loop — the agent must evaluate cost vs. value before paying

Testing

The example includes a mock paid API server (scripts/mock_paid_api.py) that simulates the full 402 → payment → 200 flow without any real blockchain transactions. Set payment.mock: true in the config.

Changed files

ci/vale/styles/config/vocabularies/nemo-agent-toolkit-examples/accept.txt (modified, +3/-0)
examples/x402_payment_tool/.gitignore (added, +3/-0)
examples/x402_payment_tool/README.md (added, +209/-0)
examples/x402_payment_tool/pyproject.toml (added, +41/-0)
examples/x402_payment_tool/scripts/mock_x402_server.py (added, +133/-0)
examples/x402_payment_tool/src/nat_x402_payment/__init__.py (added, +14/-0)
examples/x402_payment_tool/src/nat_x402_payment/configs/payment-agent.example.yml (added, +52/-0)
examples/x402_payment_tool/src/nat_x402_payment/register.py (added, +376/-0)
examples/x402_payment_tool/src/nat_x402_payment/wallet.py (added, +219/-0)

Code Example

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

# Connect agentpay-mcp server
mcp_client = BasicMCPClient("npx agentpay-mcp")
mcp_tool_spec = McpToolSpec(client=mcp_client)

tools = mcp_tool_spec.to_tool_list()
# Agent now has access to: pay, get_balance, list_transactions

RAW_BUFFERClick to expand / collapse

What's missing

LlamaIndex agents can call APIs, query databases, and orchestrate complex workflows — but there's no standard way for them to handle payments. If your agent needs to call a paid API, trigger an invoice, or make a micropayment mid-workflow, you're writing custom code from scratch every time.

The proposal

Add agentpay-mcp as a supported MCP tool in LlamaIndex's tool integrations.

Key behaviors:

Human-approval mode: agent requests payment, human approves before funds move
On-chain spend caps: hard limits enforced by smart contract, not just config
Audit trail: every payment logged with agent ID, tool call, amount, timestamp
Non-custodial: you hold your own keys

What it looks like in practice

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

# Connect agentpay-mcp server
mcp_client = BasicMCPClient("npx agentpay-mcp")
mcp_tool_spec = McpToolSpec(client=mcp_client)

tools = mcp_tool_spec.to_tool_list()
# Agent now has access to: pay, get_balance, list_transactions

Agent can then pay for premium API calls, trigger usage-based billing, or handle service-to-service payments — all without leaving the LlamaIndex workflow.

Why this matters for LlamaIndex specifically

A lot of LlamaIndex use cases touch paid services: document processing APIs, specialized data providers, SaaS integrations. Right now, payment handling is either ignored (dev pays manually out-of-band) or bolted on with custom code. A standard MCP payment tool makes this composable.

Existing MCP infrastructure

LlamaIndex already has solid MCP support via llama-index-tools-mcp. This would slot in naturally alongside existing MCP tool integrations — no new abstractions needed.

References

agentpay-mcp repo: https://github.com/up2itnow0822/agentpay-mcp
NVIDIA NeMo-Agent-Toolkit-Examples PR (merged): https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17
x402 protocol spec: https://github.com/coinbase/x402
LlamaIndex MCP tools docs: https://docs.llamaindex.ai/en/stable/examples/tools/mcp/

Happy to help draft documentation or example notebooks if this direction is interesting.

extent analysis

Fix Plan

To integrate the agentpay-mcp tool into LlamaIndex, follow these steps:

Add agentpay-mcp as a supported MCP tool in LlamaIndex's tool integrations.
Install agentpay-mcp using npm by running npm install agentpay-mcp.
Import the BasicMCPClient and McpToolSpec classes from llama_index.tools.mcp.
Create an instance of BasicMCPClient with the agentpay-mcp server URL.
Create an instance of McpToolSpec with the BasicMCPClient instance.
Convert the McpToolSpec instance to a tool list using the to_tool_list method.

Example code:

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

# Connect to agentpay-mcp server
mcp_client = BasicMCPClient("npx agentpay-mcp")
mcp_tool_spec = McpToolSpec(client=mcp_client)

# Get the list of tools
tools = mcp_tool_spec.to_tool_list()

# Agent now has access to: pay, get_balance, list_transactions

Verification

To verify that the integration is working, check that the agent can successfully use the pay tool to make payments. You can do this by:

Calling the pay tool with a valid payment amount and recipient.
Verifying that the payment is successfully processed and logged in the audit trail.

Extra Tips

Make sure to handle errors and exceptions properly when using the pay tool.
Consider adding additional logging and monitoring to track payment activity and detect any issues.
Review the agentpay-mcp documentation and the x402 protocol spec to ensure you understand the payment flow and any requirements or limitations.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#api #installation #tensor shape #autograd error #tool integration

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

llamaIndex - ✅(Solved) Fix Feature: agentpay-mcp — payment tool for LlamaIndex agents (x402, human-approval, spend caps) [1 pull requests, 1 participants]

Recommended Tools

GitHub issue graph ai analysis

Fix Action

Fix / Workaround

PR fix notes

PR #17: feat: x402 payment tool — enable agents to pay for premium APIs

Description (problem / solution / changelog)

Summary

What This Example Does

Files

Security Architecture

Why Payment Tools Are Different

Testing

Changed files

Code Example

What's missing

The proposal

What it looks like in practice

Why this matters for LlamaIndex specifically

Existing MCP infrastructure

References

extent analysis

Fix Plan

Verification

Extra Tips

Still need to ship something?

TRENDING

llamaIndex - ✅(Solved) Fix Feature: agentpay-mcp — payment tool for LlamaIndex agents (x402, human-approval, spend caps) [1 pull requests, 1 participants]

Recommended Tools

GitHub issue graph ai analysis

Fix Action

Fix / Workaround

PR fix notes

PR #17: feat: x402 payment tool — enable agents to pay for premium APIs

Description (problem / solution / changelog)

Summary

What This Example Does

Files

Security Architecture

Why Payment Tools Are Different

Testing

Changed files

Code Example

What's missing

The proposal

What it looks like in practice

Why this matters for LlamaIndex specifically

Existing MCP infrastructure

References

extent analysis

Fix Plan

Verification

Extra Tips

Still need to ship something?

RELATED_DISCOVERY

TRENDING