feat: add spraay crypto payments agent example

examples/spraay_crypto_payments/README.md

@@ -0,0 +1,156 @@
+# Spraay Crypto Payments Agent
+
+An AI agent that queries cryptocurrency data across 15 blockchains using the
+[Spraay x402 gateway](https://gateway.spraay.app). The agent can check gateway
+health, list supported chains and routes, look up wallet balances, and get
+token prices — all through natural language.
+
+## Overview
+
+This example demonstrates how to build a **crypto query agent** using NeMo
+Agent Toolkit with custom tools that interact with the Spraay x402 protocol
+gateway. The agent uses a ReAct pattern to reason about queries and execute
+them via HTTP API calls.
+
+### What is x402?
+
+The [x402 protocol](https://www.x402.org) enables AI agents to pay for API
+services using USDC micropayments over HTTP. When an agent calls a paid
+endpoint, the server returns HTTP 402 (Payment Required) with payment details.
+The agent signs a USDC transaction, resends the request with payment proof,
+and the server executes the operation.
+
+### Supported Chains
+
+Base · Ethereum · Arbitrum · Polygon · BNB Chain · Avalanche · Solana ·
+Bitcoin · Stacks · Unichain · Plasma · BOB · Bittensor · Stellar · XRP Ledger
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) package manager
+- NVIDIA API key from [build.nvidia.com](https://build.nvidia.com)
+
+## Setup
+
+1. Clone this repository and navigate to the example:
+
+```bash
+cd examples/spraay_crypto_payments
+```
+
+2. Install dependencies:
+
+```bash
+uv pip install -e .
+```
+
+3. Set environment variables:
+
+```bash
+export NVIDIA_API_KEY=<your-nvidia-api-key>
+export SPRAAY_GATEWAY_URL=https://gateway.spraay.app  # optional, this is the default
+```
+
+## Running the Example
+
+### Check gateway health
+
+```bash
+nat run \
+  --config_file configs/config.yml \
+  --input "Is the Spraay gateway healthy?"
+```
+
+### List supported chains
+
+```bash
+nat run \
+  --config_file configs/config.yml \
+  --input "What blockchains does Spraay support?"
+```
+
+### Get token price
+
+```bash
+nat run \
+  --config_file configs/config.yml \
+  --input "What is the current price of ETH on Base?"
+```
+
+## Expected Output
+
+```
+$ nat run --config_file configs/config.yml --input "Is the Spraay gateway healthy?"
+
+Configuration Summary:
+--------------------
+Workflow Type: react_agent
+Number of Functions: 5
+Number of LLMs: 1
+
+Agent's thoughts:
+Thought: The user wants to check if the Spraay gateway is healthy.
+I should use the spraay_health tool.
+Action: spraay_health
+Action Input: check health
+
+Observation: {
+  "status": "ok",
+  "version": "3.6.0",
+  "uptime": "..."
+}
+
+Thought: The gateway is healthy and running.
+Final Answer: Yes, the Spraay x402 gateway is healthy. It is running
+version 3.6.0 and reporting an "ok" status.
+------------------------------
+Workflow Result: ['Yes, the Spraay x402 gateway is healthy...']
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         NeMo Agent Toolkit              │
+│                                         │
+│  ┌───────────────────────────────────┐  │
+│  │     ReAct Agent (Llama 3.1)      │  │
+│  │                                   │  │
+│  │  Tools:                           │  │
+│  │  ├── spraay_health               │  │
+│  │  ├── spraay_routes               │  │
+│  │  ├── spraay_chains               │  │
+│  │  ├── spraay_balance              │  │
+│  │  └── spraay_price                │  │
+│  └──────────────┬────────────────────┘  │
+│                 │                        │
+└─────────────────┼────────────────────────┘
+                  │ HTTP + x402
+                  ▼
+     ┌────────────────────────┐
+     │  Spraay x402 Gateway   │
+     │  gateway.spraay.app    │
+     │                        │
+     │  84+ paid endpoints    │
+     │  15 blockchains        │
+     │  USDC micropayments    │
+     └────────────────────────┘
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `configs/config.yml` | NeMo Agent Toolkit workflow configuration |
+| `src/spraay_crypto_payments/register.py` | Tool registration with `@register_function` |
+| `src/spraay_crypto_payments/spraay_client.py` | Async HTTP client for the Spraay gateway |
+| `src/spraay_crypto_payments/__init__.py` | Package init |
+| `pyproject.toml` | Project dependencies and NAT entry points |
+
+## Links
+
+- [Spraay Gateway Docs](https://docs.spraay.app)
+- [x402 Protocol](https://www.x402.org)
+- [Spraay MCP Server](https://smithery.ai/server/@plagtech/spraay-x402-mcp)
+- [NeMo Agent Toolkit Docs](https://docs.nvidia.com/nemo/agent-toolkit/latest/)

examples/spraay_crypto_payments/configs/config.yml

@@ -0,0 +1,56 @@
+# Spraay Crypto Payments Agent
+# NeMo Agent Toolkit workflow configuration
+#
+# This agent uses the Spraay x402 gateway to execute cryptocurrency
+# payments across 15 blockchains via USDC micropayments.
+
+functions:
+  # Free query tools (no x402 payment required)
+  spraay_health:
+    _type: spraay_gateway_tool
+    gateway_url: ${SPRAAY_GATEWAY_URL:-https://gateway.spraay.app}
+    endpoint: /health
+    method: GET
+    description: "Check the health status of the Spraay x402 gateway"
+
+  spraay_routes:
+    _type: spraay_gateway_tool
+    gateway_url: ${SPRAAY_GATEWAY_URL:-https://gateway.spraay.app}
+    endpoint: /v1/routes
+    method: GET
+    description: "List all available Spraay gateway routes with pricing info"
+
+  spraay_chains:
+    _type: spraay_gateway_tool
+    gateway_url: ${SPRAAY_GATEWAY_URL:-https://gateway.spraay.app}
+    endpoint: /v1/chains
+    method: GET
+    description: "List all supported blockchains on the Spraay gateway"
+
+  spraay_balance:
+    _type: spraay_balance_tool
+    gateway_url: ${SPRAAY_GATEWAY_URL:-https://gateway.spraay.app}
+    description: "Check the token balance of a wallet address on a specific chain"
+
+  spraay_price:
+    _type: spraay_price_tool
+    gateway_url: ${SPRAAY_GATEWAY_URL:-https://gateway.spraay.app}
+    description: "Get the current price of a token on a specific chain"
+
+llms:
+  nim_llm:
+    _type: nim
+    model_name: meta/llama-3.1-70b-instruct
+    temperature: 0.0
+
+workflow:
+  _type: react_agent
+  tool_names:
+    - spraay_health
+    - spraay_routes
+    - spraay_chains
+    - spraay_balance
+    - spraay_price
+  llm_name: nim_llm
+  verbose: true
+  parse_agent_response_max_retries: 3

examples/spraay_crypto_payments/pyproject.toml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-License-Identifier: Apache-2.0
+
+[project]
+name = "spraay-crypto-payments"
+version = "0.1.0"
+description = "Spraay x402 crypto payment tools for NVIDIA NeMo Agent Toolkit"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "nvidia-nat>=1.3.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.entry-points.'nat.components']
+spraay_crypto_payments = "spraay_crypto_payments.register"

examples/spraay_crypto_payments/src/spraay_crypto_payments/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES.
+# SPDX-License-Identifier: Apache-2.0