x402geo MCP + ACP Skill
Purpose
Use this skill to run a full user-facing GEO/SEO audit flow on https://x402geo.com:
- Collect user email + target URL.
- Create a payment-required audit request.
- Return payment link and audit redirect/progress URL to the user.
- Track job progress until completion.
- Deliver report summary and public report link.
Integration Modes
Use one of these modes:
- MCP:
POST https://x402geo.com/api/mcp (JSON-RPC 2.0 tools)
- ACP:
https://x402geo.com/api/acp/* REST endpoints
If your agent supports tool-calling well, prefer MCP.
If your agent is workflow/REST oriented, prefer ACP.
Required User Inputs
Collect these first:
email: user email for payment and audit associationurl: full website URL to audit (for example https://example.com)
ACP Flow (Recommended for explicit payment lifecycle)
Step 1: Create payment request
Request:
POST https://x402geo.com/api/acp/jobs
Content-Type: application/json
{
"email": "user@example.com",
"requirements": {
"url": "https://example.com",
"report_depth": "standard"
}
}
Expected response fields:
status = payment_requiredcheckout_url (payment link)emailtarget_url
Agent action:
- If agentic wallet is funded: notify the user that a funded agentic wallet is detected and ask for confirmation before paying (e.g. "I found a funded agentic wallet. Would you like me to pay automatically using it?"). Only proceed with
mcp__agentcash__fetch (see Payment: Agentic Wallet section) after the user confirms. Do not show the checkout URL if the user confirms.
- If wallet unavailable or unfunded: return
checkout_url to user, tell them to complete payment, and explain this starts the audit flow.
Step 2: Start paid audit
After payment (or directly in local/dev setups where paywall is disabled), call:
GET https://x402geo.com/api/acp/jobs/start?url=https%3A%2F%2Fexample.com&email=user%40example.com
Expected response fields:
job_idprogress_urlresults_urlreport_urlstatus
Agent action:
- Return
progress_url as the audit status URL.
- Keep
job_id for tracking.
- Return
report_url as the final public report link placeholder.
Step 3: Track progress
Poll either endpoint until complete:
GET /api/acp/jobs/{jobId}GET /api/acp/resources/audit-status?jobId={jobId}
State mapping:
pending / in_progress: keep pollingcompleted: proceed to deliverable fetchfailed: stop and report error_reason to user
Step 4: Read and return report
Fetch deliverable:
GET https://x402geo.com/api/acp/jobs/{jobId}/deliverable
Notes:
- Returns
409 while audit is not complete.
- Returns
deliverable object when complete.
Agent action:
- Summarize key findings and recommendations for user.
- Provide
report_url from status/start response as the public report link.
MCP Flow (Tool-calling agents)
Endpoint:
POST https://x402geo.com/api/mcp
Protocol methods:
initializetools/listtools/call
Primary tools:
create_geo_audit with url and optional emailget_audit_status with jobIdget_report_links with jobId
MCP workflow:
- Check agentic wallet via
mcp__agentcash__get_balance. If funded, notify the user and ask for confirmation (e.g. "I found a funded agentic wallet. Would you like me to pay automatically using it?"). Only use mcp__agentcash__fetch to call create_geo_audit (see Payment: Agentic Wallet section below) after the user confirms.
- If wallet unavailable, unfunded, or user declines, call
create_geo_audit normally. If status=payment_required, return paymentUrl to user and ask them to complete payment.
- After payment (automatic or manual), get
jobId from the response and call get_audit_status.
- When
done, call get_report_links and return reportPage.
Payment: Agentic Wallet (Preferred, Confirm First)
Before falling back to a manual checkout link, check if the AgentCash MCP wallet is available and funded. If it is, notify the user and ask for their confirmation before proceeding.
Check wallet readiness
Call the AgentCash MCP tool:
mcp__agentcash__get_balance
- If USDC balance is sufficient to cover the audit cost (typically $1–5 USDC), ask the user: "I found a funded agentic wallet. Would you like me to pay automatically using it?"
- Only proceed after the user confirms.
- If balance is zero or insufficient, fall back to the manual payment flow and provide the
checkout_url.
Automatic payment via AgentCash MCP
Use mcp__agentcash__fetch to call the x402-gated audit endpoint. The wallet handles the USDC payment on Base automatically.
ACP payment example:
mcp__agentcash__fetch(
url: "https://x402geo.com/api/acp/jobs",
method: "POST",
body: { "email": "user@example.com", "requirements": { "url": "https://example.com", "report_depth": "standard" } }
)
MCP payment example:
mcp__agentcash__fetch(
url: "https://x402geo.com/api/mcp",
method: "POST",
body: { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "create_geo_audit", "arguments": { "url": "https://example.com", "email": "user@example.com" } }, "id": 1 }
)
On success, parse the response and continue to Step 2 (start audit). Let the user know the payment was completed.
If mcp__agentcash__fetch returns insufficient balance or authentication errors:
- Call
mcp__agentcash__list_accounts to surface a deposit link to the user.
- Fall back to returning the manual
checkout_url.
Wallet setup errors — what to tell the user
Only surface wallet issues to the user when automatic payment is impossible:
- "Insufficient balance" → "Your agentic wallet needs more USDC. I can send you a deposit link, or provide a direct payment link instead."
- "Not authenticated" → "The agentic wallet isn't set up. I can send you the payment link to complete it manually."
Always inform the user of payment outcomes — whether paid via agentic wallet or manual checkout.
Agent Output Contract
At minimum, send user:
- Payment step: if agentic wallet is available, ask for confirmation before paying; otherwise provide
checkout_url or paymentUrl for manual payment
- Tracking step:
progress_url or status page URL
- Completion step: concise summary + public
report_url/reportPage
If processing fails, send:
- current status
- provider error message
- exact next action user should take
