Skip to main content
Glama
aibtc-mcp-server
by aibtcdev

execute_x402_endpoint

Executes an x402 API endpoint and automatically handles payment, returning the paid result with transaction and fee details.

Instructions

Execute an x402 API endpoint. Payment is handled automatically.

Supported sources:

  • x402.aibtc.com (mainnet) / x402.aibtc.dev (testnet), the default: Use path like "/inference/openrouter/chat"

  • x402.biwas.xyz: Use apiUrl="https://x402.biwas.xyz" with path like "/api/pools/trending"

  • stx402.com: Use apiUrl="https://stx402.com" with path like "/registry/list"

  • aibtc.com (mainnet) / aibtc.dev (testnet): Use apiUrl="https://aibtc.com" with path like "/api/inbox/{address}"

  • Any x402-compatible URL: Use url parameter with full endpoint URL

Use list_x402_endpoints to discover available endpoints.

A paid result includes txid and gas: {sponsored, feeUstx}. Sponsored means the endpoint's relay pays the STX fee (feeUstx "0"); otherwise this wallet paid feeUstx on top of the price.

For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs a standard sBTC transfer and settles directly through the x402 facilitator.

Tip: call earning_opportunities to see how to put your assets to work.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "execute_x402_endpoint"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoFull endpoint URL (e.g., 'https://x402.aibtc.com/hashing/sha256'). Takes precedence over path+apiUrl.
dataNoRequest body for POST/PUT requests
pathNoAPI endpoint path (e.g., '/api/pools/trending'). Required if url is not provided.
assetNoWhich asset to pay with when the endpoint accepts several. Accepts a symbol ("sBTC", "STX") or a full contract identifier. Defaults to the first asset this client can pay. Only STX and sBTC can be signed; requesting any other asset returns an error listing what is accepted.
apiUrlNoAPI base URL: https:// plus the source host from list_x402_endpoints (x402.aibtc.com, x402.biwas.xyz, stx402.com, aibtc.com). Defaults to x402.aibtc.com (testnet x402.aibtc.dev).
methodNoHTTP methodGET
paramsNoQuery parameters for GET requests
autoApproveNoSkip cost probe and execute immediately. When false (default), probes first and returns cost info for paid endpoints. When true, executes atomically like before. Free endpoints always execute transparently.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.77.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does disclose key behavior: payment is handled automatically, paid results include txid and a gas breakdown, and 'sponsored' determines whether this wallet pays an STX fee on top of the price. It does not cover prerequisites (wallet unlocked), spending limits, or what happens on payment failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and payment note, then structured source routing, then result shape. The trailing 'Tip: call earning_opportunities' is promotional and not needed to invoke this tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with no annotations and no output schema, the description covers payment model, result shape, and host routing well. Gaps remain around error/failure behavior and free-vs-paid execution flow, which is only explained inside the autoApprove schema field.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description adds real value by pairing each supported host with an example path shape and by clarifying that url takes precedence over path+apiUrl. The asset-signing constraint is documented in the schema rather than the description, keeping it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Execute an x402 API endpoint') and immediately clarifies that payment is automatic, which is the defining trait. It also distinguishes itself from siblings by naming list_x402_endpoints for discovery and send_inbox_message_direct for inbox messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing rules per source (which apiUrl to pair with which path style) and an explicit exclusion: 'For aibtc.com inbox messages, use send_inbox_message_direct instead.' It also points to list_x402_endpoints as the discovery step before calling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools