agentic-scraper-provider-sdk

Agentic Scraper Provider SDK for Python

Server-side SDK for event-driven MCP Market monetization. Use it inside the MCP or API service you publish as a provider. It is separate from the Agentic Scraper client SDK used by consumers.

pip install agentic-scraper-provider-sdk

How charging works

For a Marketplace entry configured with provider_event pricing, the Agentic Scraper proxy forwards a signed x-agentic-charge-token header to your service. Report a configured event and count with charge(). Always use the returned chargedCount; it may be lower than requested when the buyer's remaining run budget is limited.

FastAPI / async example

import os

from fastapi import FastAPI, Request
from agentic_scraper_provider import AsyncAgenticProviderClient

provider = AsyncAgenticProviderClient(api_key=os.environ["AGENTIC_PROVIDER_API_KEY"])
app = FastAPI()

@app.post("/mcp")
async def mcp(request: Request):
    records = await load_records()
    result = await provider.charge(
        charge_token=request.headers["x-agentic-charge-token"],
        event_name="record-returned",
        count=len(records),
        idempotency_key=f"record-export:{request.headers.get('x-request-id')}",
        metadata={"requestedCount": len(records)},
    )
    return records[:result["chargedCount"]]

Flask / sync example

import os

from flask import Flask, request
from agentic_scraper_provider import AgenticProviderClient

provider = AgenticProviderClient(
    api_key=os.environ["AGENTIC_PROVIDER_API_KEY"],
)
app = Flask(__name__)

@app.post("/summarize")
def summarize():
    summary = create_summary(request.json["text"])
    result = provider.charge(
        charge_token=request.headers["x-agentic-charge-token"],
        event_name="summary-created",
        idempotency_key=f"summary:{request.headers.get('x-request-id')}",
    )
    return {"summary": summary} if result["chargedCount"] == 1 else {"summary": None}

Reliability rules

• Use a stable idempotency_key for every logical event.
• Return or process at most result["chargedCount"] units.
• Both clients retry transport failures, HTTP 429, and 5xx responses while preserving the same idempotency key.
• Validation and other 4xx errors are not retried.
• Verification and production use the same charge() method. Verification returns verification: true and creates no billing activity.
• Keep the provider API key and charge token on the server. Never expose or log them.

AgenticProviderClient is synchronous for Flask and other WSGI applications. AsyncAgenticProviderClient is intended for FastAPI and other ASGI services. The default API base URL is https://api.agenticscraper.com/api/v1.

Full REST and SDK documentation is available at https://docs.agenticscraper.com.