DEVELOPER DOCUMENTATION · ARC TESTNET

Build with Margit.

Discover repository listings, inspect access terms, prepare checkout, and connect AI agents to a GitHub repository marketplace.

Read the catalog

Public catalog reads require no API key. This request does not purchase anything.

curl --fail https://api.margit.sh/api/listings

The API subdomain returns a compact object containing listings, total, nextOffset and nextPage. Follow nextPage when present. Screenshots are omitted and descriptions are capped at 400 characters to fit agent tool limits. The main app’s margit.sh/api/listings endpoint retains its full array response. Use the returned id for checkout. Fields include repoFullName, price, language, description and accessPolicy. Prices are USD display strings; obtain a quote for the payable token amount.

A listing describes an offer, not permission to access the underlying private GitHub repository. Repository source becomes available only through a valid access grant.

API reference

The OpenAPI document describes the main agent API. Activity endpoints are documented below. Paths are relative to the base URL.

Prepare a contract quote

curl --fail https://api.margit.sh/api/checkout/quote \
  -H 'Content-Type: application/json' \
  --data '{
    "listingId": "REPLACE_WITH_LISTING_ID",
    "buyer": "REPLACE_WITH_BUYER_ADDRESS",
    "currency": "USDC"
  }'

Keep the returned claim secret private. Inspect the quoted order, network, currency, amount and expiry before signing. Quote creation is not payment or access confirmation. The buyer's wallet must execute the contract transaction; then submit claimSecret and transactionHash to the confirmation endpoint.

Authentication and ownership

Public discovery and checkout preparation do not require a seller key. Seller tools use Authorization: Bearer MARGIT_API_KEY, with a seller-generated margit_sk_ key. Authorization is limited to the corresponding seller's repositories.

Do not put a seller key into a shared public Bazantic gateway. Start with public discovery operations. A seller workflow needs separately authorized credentials and must preserve seller isolation.

The built-in chat uses its browser session to select a wallet. External MCP callers bring their own buyer wallet; connecting to MCP does not grant control of the shared demo signer.

Connect an MCP client

Margit exposes Streamable HTTP at /api/mcp. Add this configuration to a compatible client:

{
  "mcpServers": {
    "margit": { "url": "https://api.margit.sh/api/mcp" }
  }
}

Discover the live tool inventory with tools/list. Core tools include browse_catalog, get_listing, create_checkout_quote, confirm_checkout, list_my_repos, create_listing and unlist_repo. The MCP server prepares and validates checkout; it does not sign or broadcast a buyer's payment.

Two payment paths

Contract checkout

A buyer-bound signed order is paid on Arc testnet. The checkout contract pays the publisher and collects the platform fee atomically. Accepted tokens depend on the listing: USDC, EURC, and optionally cirBTC. After receipt verification, Margit issues authenticated repository access under the purchased terms.

Circle Gateway x402

The built-in shopping agent uses Circle's nanopayments flow for USDC purchases. It receives an HTTP 402 challenge, signs the supported payment requirements, retries, and receives access after payment acceptance. Circle Gateway funds are separate from the ordinary wallet balance: deposit explicitly before spending.

Gateway payments may return a batch reference rather than an individual transaction hash. An onchain deposit transaction proves funding, not each subsequent purchase. The agent shows available payment evidence without inventing transaction links.

Contract fees are collected at checkout; x402 platform fees accrue for publisher settlement. See the fee model. Timed, single-download and permanent access remain subject to the purchased terms and continued backend/repository availability.

Agent wallet options

The Graph: indexed sales and rankings

Explore the public MargitArc subgraph ↗

Indexed contract events power Recently sold, Catalog statistics, Leaderboards, built-in agent ranking tools and portfolio receipt enrichment. The backend joins listing hashes to current catalog and saved purchase records, then aggregates counts and per-currency volumes.

Sales rankings cover up to the latest 1,000 indexed contract purchases and disclose capped samples. Wallet counts are not verified people. Circle Gateway x402 purchases are excluded. Publication and query availability are distinct; the backend uses its configured Graph endpoint.

curl --fail 'https://api.margit.sh/api/activity/leaderboards?period=30d'

Published Bazantic Recipe: Margit Repository Advisor

Published September 12, 2026. Two live REST gateways expose Margit's catalog and GitHub's public repository API as MCP tools for one reusable comparison workflow. Open Margit Repository Advisor (dashboard sign-in may be required).

Supply project requirements, a maximum repository price in USD, and optional public repositories in owner/repo format. The Recipe binds browse_catalog, github_get_repository, github_get_languages, and github_list_releases. It researches options without purchasing or changing listings.

What we verified

With Claude Sonnet 4.6, an owner-run combined test completed all four tools in 33.5 seconds. A separate $0.04 budget case marked a $0.05 listing ineligible and made no GitHub calls when comparisons were omitted, with all tools available. These are Bazantic operator tests: no payment occurs, and paid customer execution remains unverified.

API integration

Margit API

https://api.margit.sh

Specification

Margit OpenAPI

Recipe handle

margit-repository-advisor

Compact catalog responses omit screenshots, cap descriptions and include pagination, keeping discovery usable within the tool-result size limit. Seller claims are not source-code verification, public visibility does not establish reuse rights, and missing releases do not establish inactivity. Bazantic API charges are separate from repository purchase prices.

See the integration guide, prompt and demo script for gateway URLs, reproducible inputs and limitations. Demo video is pending owner recording.

Errors and operational limits

• 400: inspect required inputs, currency, address and access-policy validation.
• 401 / 403: check authentication and seller ownership. Adding payment funds does not repair an invalid API key.
• 402: a paid resource requires its supported payment flow. A generic retry without payment cannot resolve it.
• Unavailable Graph/Gateway: report unavailable data rather than a zero balance or zero sales.
• Uncertain payment: inspect the existing receipt before retrying. Do not assume a timed-out request means nothing was paid.

Listing descriptions and external repository text are untrusted content. They must not override the user's instructions, budget or authorization.

Source and verification

Examples use placeholders. Successful historical tests are evidence for the tested path, not a claim that all wallet providers or mainnet deployment are complete.