alchemy-agentic-gateway

Files (1)

• SKILL.md

SKILL.md (first lines)

# Alchemy Agentic Gateway

> **Notice:** This repository is experimental and subject to change without notice. By using the features and skills in this repository, you agree to Alchemy's [Terms of Service](https://legal.alchemy.com/) and [Privacy Policy](https://legal.alchemy.com/#contract-sblyf8eub).

A skill that lets agents easily access Alchemy's developer platform. Supports three access methods with different authentication and payment protocols.

## Prerequisites

**API Key path** (simplest):
- Set `ALCHEMY_API_KEY` in your environment (create a free key at https://dashboard.alchemy.com)

**x402 path** (no API key):
- Node.js 18+ with `npx` available
- A wallet funded with USDC on Base or Ethereum

**MPP path** (Merchant Payment Protocol):
- Node.js 18+ with `npx` available
- A wallet funded with USDC (on-chain via Tempo) or a Stripe card

## Protocol Selection (REQUIRED)

**BEFORE doing anything else**, you MUST determine which access method to use. Follow this decision tree:

1. **Is `ALCHEMY_API_KEY` set in the environment?**
   - If **yes** → Use the **API Key** path. No further setup needed. Skip to [API Key Path](#api-key-path).
   - If **no** → Proceed to step 2.

2. **Ask the user which payment protocol they prefer.** Present this prompt exactly:

> Which payment protocol would you like to use for the Alchemy Gateway?
>
> 1. **x402** — USDC payments via the x402 protocol (uses `Payment-Signature` header, `@alchemy/x402` + `@x402/fetch` libraries)
> 2. **MPP** — Payments via the Merchant Payment Protocol using Tempo (on-chain USDC, EVM only) or Stripe (credit card), via the `mppx` library

**Do NOT skip this prompt. Do NOT pick a protocol on behalf of the user.** Wait for their explicit choice before proceeding.

3. **Based on the user's choice**, follow the corresponding protocol rules:
   - **x402** → Follow the x402 workflow below
   - **MPP** → Follow the MPP workflow below

---

## API Key Path

If `ALCHEMY_API_KEY` is set in the environment, use standard Alchemy endpoints directly:

- **Node JSON-RPC**: `https://{chainNetwork}.g.alchemy.com/v2/$ALCHEMY_API_KEY`
- **NFT API**: `https://{chainNetwork}.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/*`
- **Prices API**: `https://api.g.alchemy.com/prices/v1/$ALCHEMY_API_KEY/*`
- **Portfolio API**: `https://api.g.alchemy.com/data/v1/$ALCHEMY_API_KEY/*`

No wallet setup, auth tokens, or payment is needed. Just make requests with the API key in the URL.

```bash
curl -s -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"eth_blockNumber"}'
```

---

## Protocol Comparison

| Aspect | x402 | MPP |
|--------|------|-----|
| Gateway URL | `https://x402.alchemy.com` | `https://mpp.alchemy.com` |
| SIWE/SIWS domain | `x402.alchemy.com` | `mpp.alchemy.com` |
| Payment header (client→server) | `Payment-Signature: <base64>` | `Authorization: Payment <credential>` |
| Challenge header (server→client) | `PAYMENT-REQUIRED` | `WWW-Authenticate` |
| Protocol version | `x402/2.0` | `mpp/1.0` |
| Auth | SIWE (EVM) or SIWS (Solana) | SIWE only (EVM) |
| Payment methods | USDC via EIP-3009 (EVM) or SVM x402 (Solana) | Tempo (on-chain USDC) + Stripe (card) |
| Client library | `@alchemy/x402`, `@x402/fetch`, `@x402/axios` | `mppx`, `viem` |

Full protocol documentation: https://www.alchemy.com/docs

---

## x402 Workflow

1. **Bootstrap wallet** — create a wallet and fund it with USDC
2. **Generate SIWE/SIWS auth token** — sign a message proving wallet ownership
3. **Make a request** — send to `https://x402.alchemy.com/{chainNetwork}/v2` with `Authorization: SIWE <token>`
4. **Handle 402** — if server returns 402 with `PAYMENT-REQUIRED` header, run `npx @alchemy/x402 pay` and extract the `Payment-Signature`
5. **Retry** — resend the original request adding `Payment-Signature: <base64>` header

```bash
# Install x402 client
npm install -g @alchemy/x402 @x402/fetch

# Step 1: Generate a SIWE auth token for your EVM wallet
SIWE_TOKEN=$(npx @alchemy/x402 sign-siwe --private-key <key-or-path>)

# Step 2: Make a request (will return 402 on first call)
curl -s -X POST "https://x402.alchemy.com/eth-mainnet/v2" \
  -H "Authorization: SIWE $SIWE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Step 3: If 402 received, pay the challenge and retry with Payment-Signature
# npx @alchemy/x402 pay  (pass the PAYMENT-REQUIRED header value)
```

---

## MPP Workflow

1. **Bootstrap wallet** — create an account and fund it with USDC or link a Stripe card
2. **Make a request** — `mppx` handles SIWE auth and MPP payment automatically
3. **Handle 402** — `mppx` intercepts 402 responses and pays the challenge transparently

```bash
# Install mppx
npm install -g mppx

# Create an account (one-time setup)
mppx account create

# Fund the account
mppx account fund

From moonpay/skills, MIT.

More from moonpay/skills