Purch 公共 API

基础 URL:https://api.purch.xyz

速率限制

每个 IP 地址每分钟 60 个请求。每个响应中的头部信息包含：

• X-RateLimit-Limit: 每个时间窗口的最大请求数
• X-RateLimit-Remaining: 剩余请求数
• X-RateLimit-Reset: 距离重置的秒数

端点

GET /search - 结构化产品搜索

使用筛选器查询产品。

curl "https://api.purch.xyz/search?q=headphones&priceMax=100"

参数：

响应：

{
  "products": [
    {
      "id": "B0CXYZ1234",
      "title": "Sony WH-1000XM5",
      "price": 348.00,
      "currency": "USD",
      "rating": 4.8,
      "reviewCount": 15420,
      "imageUrl": "https://...",
      "productUrl": "https://amazon.com/dp/B0CXYZ1234",
      "source": "amazon"
    }
  ],
  "totalResults": 20,
  "page": 1,
  "hasMore": true
}

POST /shop - AI购物助手

自然语言产品搜索。从亚马逊和Shopify返回20多个产品。

curl -X POST "https://api.purch.xyz/shop" \
  -H "Content-Type: application/json" \
  -d '{"message": "comfortable running shoes under $100"}'

请求体：

{
  "message": "comfortable running shoes under $100",
  "context": {
    "priceRange": { "min": 0, "max": 100 },
    "preferences": ["comfortable", "breathable"]
  }
}

响应：

{
  "reply": "Found 22 running shoes. Top pick: Nike Revolution 6 at $65...",
  "products": [
    {
      "asin": "B09XYZ123",
      "title": "Nike Revolution 6",
      "price": 65.00,
      "currency": "USD",
      "rating": 4.5,
      "reviewCount": 8420,
      "imageUrl": "https://...",
      "productUrl": "https://amazon.com/dp/B09XYZ123",
      "source": "amazon"
    },
    {
      "asin": "gid://shopify/p/abc123",
      "title": "Allbirds Tree Runners",
      "price": 98.00,
      "source": "shopify",
      "productUrl": "https://allbirds.com/products/tree-runners",
      "vendor": "Allbirds"
    }
  ]
}

POST /buy - 创建采购订单

创建订单并获取待签名的交易。链根据钱包格式自动检测：

• Solana钱包（base58编码）：7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
• Base/EVM 钱包（0x）：0x1234567890abcdef1234567890abcdef12345678

亚马逊商品（Solana）：

curl -X POST "https://api.purch.xyz/buy" \
  -H "Content-Type: application/json" \
  -d '{
    "asin": "B0CXYZ1234",
    "email": "buyer@example.com",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "shippingAddress": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US",
      "phone": "+1-555-123-4567"
    }
  }'

亚马逊商品（Base）：

curl -X POST "https://api.purch.xyz/buy" \
  -H "Content-Type: application/json" \
  -d '{
    "asin": "B0CXYZ1234",
    "email": "buyer@example.com",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "shippingAddress": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }'

Shopify 商品- 使用productUrl和variantId：

curl -X POST "https://api.purch.xyz/buy" \
  -H "Content-Type: application/json" \
  -d '{
    "productUrl": "https://store.com/products/item-name",
    "variantId": "41913945718867",
    "email": "buyer@example.com",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "shippingAddress": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }'

响应：

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "awaiting-payment",
  "serializedTransaction": "NwbtPCP62oXk5fmSrgT...",
  "product": {
    "title": "Sony WH-1000XM5",
    "imageUrl": "https://...",
    "price": { "amount": "348.00", "currency": "usdc" }
  },
  "totalPrice": { "amount": "348.00", "currency": "usdc" },
  "checkoutUrl": "https://www.crossmint.com/checkout/550e8400..."
}

CLI 脚本

此技能包含适用于所有端点的即用型 CLI 脚本。提供 Python 和 TypeScript/Bun 版本。

依赖项（Solana）：

# Python
pip install solana solders base58

# TypeScript/Bun
bun add @solana/web3.js bs58

依赖项（Base/EVM）：

# TypeScript/Bun
bun add viem

搜索商品

# Python
python scripts/search.py "wireless headphones" --price-max 100
python scripts/search.py "running shoes" --brand Nike --page 2

# TypeScript
bun run scripts/search.ts "wireless headphones" --price-max 100

AI 购物助手

# Python
python scripts/shop.py "comfortable running shoes under $100"

# TypeScript
bun run scripts/shop.ts "wireless headphones with good noise cancellation"

创建订单（无需签名）

# Amazon by ASIN
python scripts/buy.py --asin B0CXYZ1234 --email buyer@example.com \
  --wallet 7xKXtg... --address "John Doe,123 Main St,New York,NY,10001,US"

# Shopify product
bun run scripts/buy.ts --url "https://store.com/products/item" --variant 41913945718867 \
  --email buyer@example.com --wallet 7xKXtg... --address "John Doe,123 Main St,NYC,NY,10001,US"

地址格式：姓名，地址行1，城市，州/省，邮政编码，国家[，地址行2][，电话]

创建订单并签名交易（Solana）

端到端购买流程 - 创建订单并签名/提交Solana交易：

# Python
python scripts/buy_and_sign.py --asin B0CXYZ1234 --email buyer@example.com \
  --wallet 7xKXtg... --private-key 5abc123... \
  --address "John Doe,123 Main St,New York,NY,10001,US"

# TypeScript
bun run scripts/buy_and_sign.ts --url "https://store.com/products/item" --variant 41913945718867 \
  --email buyer@example.com --wallet 7xKXtg... --private-key 5abc123... \
  --address "John Doe,123 Main St,NYC,NY,10001,US"

创建订单并签名交易（Base链）

使用Base/EVM钱包的端到端购买流程：

bun run scripts/buy_and_sign_base.ts --asin B0CXYZ1234 --email buyer@example.com \
  --wallet 0x1234567890abcdef1234567890abcdef12345678 \
  --private-key 0xabc123... \
  --address "John Doe,123 Main St,New York,NY,10001,US"

仅签名交易（Solana）

如果您已通过/buy接口获得序列化交易数据：仅签名交易（Base链）

# Python
python scripts/sign_transaction.py "<serialized_tx>" "<private_key_base58>"

# TypeScript
bun run scripts/sign_transaction.ts "<serialized_tx>" "<private_key_base58>"

输出（Solana）：

bun run scripts/sign_transaction_base.ts "<serialized_tx_hex>" "<private_key_hex>"

输出（Base链）：

✅ Transaction successful!
   Signature: 5UfgJ3vN...
   Explorer:  https://solscan.io/tx/5UfgJ3vN...

通过编程方式签名交易

✅ Transaction successful!
   Hash:     0x1234...
   Explorer: https://basescan.org/tx/0x1234...

适用于不使用捆绑脚本的自定义集成：

JavaScript/TypeScript

React配合钱包适配器

import { Connection, Transaction, clusterApiUrl } from "@solana/web3.js";
import bs58 from "bs58";

async function signAndSendTransaction(
  serializedTransaction: string,
  wallet: { signTransaction: (tx: Transaction) => Promise<Transaction> }
) {
  // Decode the base58 transaction
  const transactionBuffer = bs58.decode(serializedTransaction);
  const transaction = Transaction.from(transactionBuffer);

  // Sign with user's wallet (e.g., Phantom, Solflare)
  const signedTransaction = await wallet.signTransaction(transaction);

  // Send to Solana network
  const connection = new Connection(clusterApiUrl("mainnet-beta"));
  const signature = await connection.sendRawTransaction(
    signedTransaction.serialize()
  );

  // Confirm transaction
  await connection.confirmTransaction(signature, "confirmed");

  return signature;
}

Python（使用solana-py）

import { useWallet, useConnection } from "@solana/wallet-adapter-react";
import { Transaction } from "@solana/web3.js";
import bs58 from "bs58";

function CheckoutButton({ serializedTransaction }: { serializedTransaction: string }) {
  const { signTransaction, publicKey } = useWallet();
  const { connection } = useConnection();

  const handlePayment = async () => {
    if (!signTransaction || !publicKey) {
      throw new Error("Wallet not connected");
    }

    // Decode and sign
    const tx = Transaction.from(bs58.decode(serializedTransaction));
    const signed = await signTransaction(tx);

    // Send and confirm
    const sig = await connection.sendRawTransaction(signed.serialize());
    await connection.confirmTransaction(sig, "confirmed");

    console.log("Payment complete:", sig);
  };

  return <button onClick={handlePayment}>Pay with USDC</button>;
}

签名Base/EVM交易

import base58
from solana.rpc.api import Client
from solana.transaction import Transaction
from solders.keypair import Keypair

def sign_and_send(serialized_tx: str, keypair: Keypair) -> str:
    # Decode base58 transaction
    tx_bytes = base58.b58decode(serialized_tx)
    transaction = Transaction.deserialize(tx_bytes)

    # Sign
    transaction.sign(keypair)

    # Send
    client = Client("https://api.mainnet-beta.solana.com")
    result = client.send_transaction(transaction)

    return result.value  # transaction signature

对于Base链订单，

序列化交易数据是需使用EVM钱包签名的EVM交易。is an EVM transaction that needs to be signed with an EVM wallet.

使用 viem 的 TypeScript

import { createWalletClient, http, parseTransaction } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

async function signAndSendBaseTransaction(
  serializedTransaction: string,
  privateKey: `0x${string}`
) {
  const account = privateKeyToAccount(privateKey);

  const client = createWalletClient({
    account,
    chain: base,
    transport: http(),
  });

  // Parse and send the serialized transaction
  const tx = parseTransaction(serializedTransaction as `0x${string}`);
  const hash = await client.sendTransaction(tx);

  console.log("Transaction hash:", hash);
  console.log("Explorer: https://basescan.org/tx/" + hash);

  return hash;
}

使用 wagmi 的 React

import { useSendTransaction } from "wagmi";
import { parseTransaction } from "viem";

function CheckoutButton({ serializedTransaction }: { serializedTransaction: string }) {
  const { sendTransaction } = useSendTransaction();

  const handlePayment = async () => {
    const tx = parseTransaction(serializedTransaction as `0x${string}`);
    sendTransaction(tx);
  };

  return <button onClick={handlePayment}>Pay with USDC on Base</button>;
}

完整结账流程（Solana）

// 1. Search for products
const searchResponse = await fetch("https://api.purch.xyz/shop", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "wireless headphones under $100" })
});
const { products, reply } = await searchResponse.json();

// 2. User selects a product, create order (Solana wallet)
const orderResponse = await fetch("https://api.purch.xyz/buy", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    asin: products[0].asin,
    email: "buyer@example.com",
    walletAddress: wallet.publicKey.toBase58(), // Solana address
    shippingAddress: {
      name: "John Doe",
      line1: "123 Main St",
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US"
    }
  })
});
const { orderId, serializedTransaction, checkoutUrl } = await orderResponse.json();

// 3. Sign and send Solana transaction
const tx = Transaction.from(bs58.decode(serializedTransaction));
const signed = await wallet.signTransaction(tx);
const signature = await connection.sendRawTransaction(signed.serialize());
await connection.confirmTransaction(signature, "confirmed");

console.log(`Order ${orderId} paid. Tx: ${signature}`);

完整结账流程（Base）

import { parseTransaction } from "viem";

// 1. Search for products
const searchResponse = await fetch("https://api.purch.xyz/shop", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "wireless headphones under $100" })
});
const { products } = await searchResponse.json();

// 2. User selects a product, create order (EVM wallet)
const orderResponse = await fetch("https://api.purch.xyz/buy", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    asin: products[0].asin,
    email: "buyer@example.com",
    walletAddress: "0x1234...", // Base/EVM address - chain auto-detected
    shippingAddress: {
      name: "John Doe",
      line1: "123 Main St",
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US"
    }
  })
});
const { orderId, serializedTransaction } = await orderResponse.json();

// 3. Sign and send Base transaction
const tx = parseTransaction(serializedTransaction as `0x${string}`);
const hash = await walletClient.sendTransaction(tx);

console.log(`Order ${orderId} paid. Tx: ${hash}`);

备选方案：浏览器结账

如果钱包签名失败或不可用，则重定向至checkoutUrl以进行基于浏览器的支付：

if (!wallet.connected) {
  window.open(checkoutUrl, "_blank");
}

错误处理

所有端点返回的错误格式如下：

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid email format",
  "details": { "field": "email" }
}

常见错误代码：

• VALIDATION_ERROR(400) - 请求参数无效
• NOT_FOUND(404) - 未找到产品
• RATE_LIMITED(429) - 请求过多
• INTERNAL_ERROR(500) - 服务器错误