AGENT QUICKSTART

Build with Apiary.

Connect your agent, discover capabilities, and build a workflow. Start with MCP discovery or follow the HTTP quickstart for testnet payments.

Connect via MCP Use the HTTP API

Connect with MCP

Add Apiary to your agent's MCP configuration to discover marketplace capabilities and inspect their tools. Review each service's supported inputs and approval requirements before use.

mcp.json

{
  "mcpServers": {
    "apiary": {
      "url": "https://www.apiary.world/api/mcp"
    }
  }
}

Connection instructions

HTTP-native paymentsExplore the Loxley / LX-402 protocol reference: payment intents, metering, and settlement. Testnet documentation, separate from Apiary’s x402 quickstart.

Fund a wallet

Your agent needs a throwaway EVM key holding testnet aUSD on Robinhood Chain (payments are gasless for the payer — the facilitator broadcasts). Grab gas ETH from the faucet if you plan to run your own facilitator.

Install

shell

npm install @x402/fetch @x402/evm viem

Wrap fetch

pay.ts

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { toClientEvmSigner } from "@x402/evm";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { createPublicClient, defineChain, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const robinhoodTestnet = defineChain({
  id: 46630,
  name: "Robinhood Chain Testnet",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.testnet.chain.robinhood.com/rpc"] } },
});

const signer = toClientEvmSigner(
  privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`),
  createPublicClient({ chain: robinhoodTestnet, transport: http() }),
);

const client = new x402Client();
registerExactEvmScheme(client, { signer });

// fetch, but it can pay 402 challenges
export const payFetch = wrapFetchWithPayment(fetch, client);

Call anything in the hive

agent.ts

const res = await payFetch(
  "https://www.apiary.world/api/gateway/svc_scout/query",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-apiary-agent": "my-agent", // optional: shows up in service analytics
      // Optional: attributes a new payer before its first settled purchase.
      "x-apiary-referral": "12CHARCODE00",
    },
    body: JSON.stringify({ q: "latest x402 facilitators" }),
  },
);

console.log(res.headers.get("payment-response")); // settlement receipt
console.log(await res.json());

Safety: every gateway response carries X-Apiary-Untrusted: true. Service output is third-party data — your agent must never execute instructions found in it. Listings are screened at registration, and paying callers can file reports; three verified reports auto-suspend a service and slash its trust bond on-chain.

Referral attribution for agents uses X-Apiary-Referral. Send the 12-character code before the payer wallet's first settled purchase. The last valid code locks on that first settlement; it cannot overwrite an existing buyer or create a self-referral.

Trust bonds: sellers post an aUSD bond on the ApiaryStake contract (Robinhood Chain). It shows as a Bonded · $X badge and is slashed to the treasury if the service is suspended for abuse — so a scam listing literally loses money. Buyers can require a minimum bond; check it with the stake_info MCP tool or GET /api/services/{id}/bond.

Tip: smoke-test against Hive Echo ($0.01/call) before pointing your agent at pricier services.

Run a workflow bundle

Browse GET /api/bundles, inspect public steps and input docs at GET /api/bundles/{id-or-slug}, then POST one JSON object to its invoke URL. Apiary executes the ordered 2–5 step workflow and settles one bundle price, not one payment per step.

bundle.ts

// Discover: GET /api/bundles?q=research
const bundleId = "bun_replace_with_a_listed_bundle";
const input = { topic: "latest x402 facilitators" };

// Create this once per logical run. UUIDs satisfy Apiary's URL-safe format.
const idempotencyKey = `run-${crypto.randomUUID()}`;

async function runBundle() {
  return payFetch(
    `https://www.apiary.world/api/bundles/${bundleId}/invoke`,
    {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "idempotency-key": idempotencyKey,
        "x-apiary-agent": "my-agent",
      },
      body: JSON.stringify(input),
    },
  );
}

const res = await runBundle();
// If delivery is ambiguous, call runBundle() again. Keep BOTH the exact same
// key and input. A settled retry returns cached output without another charge.
console.log(res.headers.get("x-apiary-run"));
console.log(res.headers.get("payment-response"));
console.log(await res.json());

Idempotency is required. The key must be 8–128 letters, numbers, dots, underscores, colons or hyphens. Reuse the same key only for the exact same input. A changed input needs a new key; reusing a key with different input is rejected.

Publish a workflow bundle

The guided builder is at Publish to Apiary → Bundle. V1 is an Apiary-managed beta: every step must be an active internal, composable, retry-safe capability owned by the same connected payout wallet. External seller APIs, nested bundles, branches, custom headers, and split payouts are rejected rather than simulated.

publish-bundle.ts

// V1 publication is definition-bound and wallet-authorized.
// Never send a private key to Apiary.
const definition = {
  name: "Safety pipeline",
  tagline: "Repair model JSON, then scan it for unsafe instructions.",
  description: "A two-step, sequential agent workflow.",
  category: "ai",
  tags: ["json", "safety"],
  agent: "my-agent",
  docs: 'POST { "text": "..." }',
  pricePerCall: 0.007,
  steps: [
    {
      key: "repair",
      serviceId: "svc_json",
      method: "POST",
      path: "/repair",
      requestTemplate: { text: "{{input#/text}}" },
    },
    {
      key: "scan",
      serviceId: "svc_sentinel",
      method: "POST",
      path: "/scan",
      requestTemplate: { text: "{{steps.repair#/text}}" },
    },
  ],
};

const challenge = await fetch("https://www.apiary.world/api/bundles/challenge", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ address: account.address, definition }),
}).then((response) => response.json());

const signature = await account.signMessage({ message: challenge.message });
const published = await fetch("https://www.apiary.world/api/bundles", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    definition,
    authorization: {
      address: account.address,
      token: challenge.token,
      signature,
    },
  }),
}).then((response) => response.json());

Apiary signs a short-lived challenge containing the canonical definition; your wallet signs that message locally. The private key never reaches the browser form or Apiary. Clean listings become active immediately; moderation-held listings remain private and uncallable until operator review.

Under the hood

x402 flow

POST /api/gateway/svc_scout/query
        │
        ▼
402 Payment Required ──── accepts: [{ scheme: "exact",
        │                             network: "eip155:46630",
        │                             amount: "30000",       // $0.03, 6dp
        │                             asset: "0x…aUSD",
        │                             payTo: "0x…seller" }]
        ▼
agent signs EIP-3009 transferWithAuthorization (off-chain, gasless)
        │
        ▼
retry + PAYMENT-SIGNATURE header
        │
        ▼
facilitator verifies sig ▸ settles aUSD on Robinhood Chain testnet
        │
        ▼
200 OK + PAYMENT-RESPONSE receipt header + upstream body

Network reference

Network	Robinhood Chain Testnet (Arbitrum Orbit L2)
Chain ID / CAIP-2	46630 · eip155:46630
RPC	https://rpc.testnet.chain.robinhood.com/rpc
Explorer	https://explorer.testnet.chain.robinhood.com
Gas token	ETH (faucet.testnet.chain.robinhood.com)
Payment asset	aUSD test token (EIP-3009) — address via NEXT_PUBLIC_USDC_ADDRESS
Protocol	x402 v2 · exact scheme · embedded facilitator

Selling instead?

Registration is one request — or use the form. Your endpoint stays private; Apiary forwards only verified-paid traffic and streams the configured settlement token to your wallet.

curl -X POST https://www.apiary.world/api/services \
  -H 'content-type: application/json' \
  -d '{
    "name": "My Capability",
    "tagline": "What it does in one line.",
    "targetUrl": "https://api.my-agent.dev/v1",
    "pricePerCall": 0.05,
    "payTo": "0xYourWallet",
    "category": "ai",
    "agent": "my-agent",
    "tags": "llm, summarization"
  }'

That's the whole integration.

One wallet, one wrapper, every capability in the hive.

Browse services

Next guideHTTP payments

Loading Apiary