Skip to main content
Glama

Start a purchase

start_purchase

Reserve a listing for the signed-in buyer and get a one-time NEAR Intents deposit address and the exact amount of pay_with to send. Nothing is charged by this call: the purchase completes only when the buyer's own wallet sends that exact amount to that address before the deadline. Returns a checkout_id, the deposit address, exact amount, asset, chain and the pay_before deadline. If the seller accepted the buyer's offer, the agreed price is used. Requires a Port66 session (Authorization: Bearer token from wallet sign-in). Then poll purchase_status until it is paid.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "pay_with": "<pay_with>",
      "refund_to": "<refund_to>",
      "shipping_address": "<shipping_address>"
    },
    "name": "start_purchase"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe listing's id, exactly as returned in the `id` field of search_listings results (a slug such as 'kaws-x-sesame-street-water-parade-elmo-figure').
chainNoOnly needed when the asset exists on several chains: ETH and USDC on Ethereum, Arbitrum or Base, USDC also on NEAR. Omit it otherwise.
pay_withYesThe crypto asset the buyer pays with. payment_options lists which chains each one is accepted on.
refund_toYesThe buyer's own wallet address on the paying chain (for example a 0x address for Ethereum or Base, a Solana address for SOL). If the payment cannot complete, the funds are returned here. Never an exchange deposit address.
shipping_addressYesWhere the piece is shipped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changed
    • changedInput schema / properties / chain / description
      Previous value: -"Optional chain when the asset exists on several, e.g. Arbitrum for ETH"New value: +"Only needed when the asset exists on several chains: ETH and USDC on Ethereum, Arbitrum or Base, USDC also on NEAR. Omit it otherwise."
    • addedInput schema / properties / chain / enum
      Added value: +[
      +  "Bitcoin",
      +  "Solana",
      +  "NEAR",
      +  "Ethereum",
      +  "Arbitrum",
      +  "Base",
      +  "Dogecoin",
      +  "Litecoin"
      +]
    • changedInput schema / properties / id / description
      Previous value: -"Listing id (the slug from search_listings)"New value: +"The listing's id, exactly as returned in the `id` field of search_listings results (a slug such as 'kaws-x-sesame-street-water-parade-elmo-figure')."
    • addedInput schema / properties / id / minLength
      Added value: +1
    • changedInput schema / properties / pay_with / description
      Previous value: -"What the buyer pays with: BTC, SOL, NEAR, ETH, USDC, USDT, DOGE or LTC"New value: +"The crypto asset the buyer pays with. payment_options lists which chains each one is accepted on."
    • addedInput schema / properties / pay_with / enum
      Added value: +[
      +  "BTC",
      +  "SOL",
      +  "NEAR",
      +  "ETH",
      +  "USDC",
      +  "USDT",
      +  "DOGE",
      +  "LTC"
      +]
    • changedInput schema / properties / refund_to / description
      Previous value: -"The buyer's own address on the paying chain; refunds go here"New value: +"The buyer's own wallet address on the paying chain (for example a 0x address for Ethereum or Base, a Solana address for SOL). If the payment cannot complete, the funds are returned here. Never an exchange deposit address."
    • changedInput schema / properties / shipping_address / description
      Previous value: -"Where the piece is shipped"New value: +"Where the piece is shipped."
    • addedInput schema / properties / shipping_address / properties / city / description
      Added value: +"City or town."
    • addedInput schema / properties / shipping_address / properties / country / description
      Added value: +"Country, e.g. 'United States' or 'GB'."
    • addedInput schema / properties / shipping_address / properties / line1 / description
      Added value: +"Street address."
    • addedInput schema / properties / shipping_address / properties / line2 / description
      Added value: +"Apartment, suite or building (optional)."
    • addedInput schema / properties / shipping_address / properties / name / description
      Added value: +"Recipient's full name."
    • addedInput schema / properties / shipping_address / properties / phone / description
      Added value: +"Phone number for the courier (optional)."
    • addedInput schema / properties / shipping_address / properties / postal / description
      Added value: +"Postcode or ZIP code."
    • addedInput schema / properties / shipping_address / properties / region / description
      Added value: +"State, province or region (optional)."
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Adds substantial behavior beyond the annotations: nothing is charged by this call, completion requires the buyer's wallet to send the exact amount before the deadline, and the auth requirement (Port66 session Bearer token) is disclosed. The annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false), so this is strong added context, though refund timing/expiry mechanics are only partially covered.

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

Conciseness5/5

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

Front-loads the core action and the no-charge guarantee, then the return values, then the auth prerequisite and follow-up. Dense but every sentence carries information an agent needs.

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

Completeness5/5

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

No output schema exists, yet the description enumerates the return fields (checkout_id, deposit address, amount, asset, chain, pay_before deadline) and the auth requirement. For a 5-parameter mutation with nested shipping object, nothing essential is missing.

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 the baseline is 3, but the description adds meaning: `pay_with` must match the exact amount returned, `refund_to` is the buyer's own wallet, and the agreed offer price overrides the listing price. That is genuine semantic value beyond the schema.

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 ('Reserve a listing for the signed-in buyer') plus the concrete artifact returned (one-time NEAR Intents deposit address and exact amount). This clearly separates it from siblings like purchase_status (polling) and make_offer (pre-purchase negotiation).

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

Usage Guidelines4/5

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

Gives clear context for when to call it and an explicit next step ('poll purchase_status until it is `paid`'), plus the offer-price condition. It does not explicitly state when not to use it (e.g., use make_offer first if no offer exists), so it falls short of full when/when-not guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources