Agent API · v1.2

SEO checks for agent workflows.

Choose a plan, create a scan, pay through NanSwap Pay, poll the order and fetch the finished report. No account. No API key. No browser widget.

PaymentNanSwap Pay API
AuthenticationNone
OutputJSON, CSV, print/PDF
Report retention14 days

AI setup

Hand your coding agent the integration.

Copy this prompt into Codex, Claude Code, Cursor or another coding agent. It points to the live contract and tells the agent to use current plan IDs, prices, error handling and payment instructions.

Copy-ready prompt

Set up a nanoSEO audit workflow

It covers discovery, order creation, payment handoff, polling, report retrieval and the 14-day retention window. Replace the bracketed values before running it.

Preview and edit the prompt

Your edits are included when you copy the prompt. The agent should verify plan details against the live catalog before creating an order.

Quickstart

One request starts the purchase.

Fetch the live plan IDs first. Then post the URL you want audited and accept the terms. The response contains the status URL, the exact crypto amount to send, and every URL needed to poll and retrieve the report.

1 · Create an orderPOST /api/v1/agent/orders
curl -X POST https://nano-seo.com/api/v1/agent/orders \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: 7d444840-9dc0-11e8-8443-0242ac110002' \
  -d '{
    "package_id": "site-10",
    "target_url": "https://example.com",
    "category_id": "general",
    "scan_mode": "auto",
    "payin_currency": "XNO",
    "terms_accepted": true
  }'
2 · Follow the response201 Created · example values
{
  "schema_version": "1.2",
  "order_id": "0f31c8a5...",
  "channel": "agent",
  "status": "pending_payment",
  "demo": false,
  "plan": { "id": "site-10", "name": "Site Audit", "page_limit": 10 },
  "target_url": "https://example.com/",
  "category_id": "general",
  "scan": { "mode": "auto", "selected_urls": [] },
  "amount": { "cents": 200, "currency": "USD", "display": "2.00" },
  "payment": {
    "provider": "nanswap",
    "demo": false,
    "status": "waiting",
    "invoice_id": "inv_example",
    "payin_currency": "XNO",
    "currency_to_send": "XNO",
    "amount_to_send": 0.125,
    "amount_to_send_exact": "0.125",
    "do_not_round": true,
    "expected_amount_from": 0.125,
    "deposit_address": "nano_example",
    "deposit_tag": null,
    "price_amount": 2,
    "price_currency": "USD",
    "fiat_price_amount": 2,
    "fiat_price_currency": "USD",
    "payment_url": "https://pay.example/invoice",
    "expires_at": "2026-11-08T12:05:00.000Z"
  },
  "urls": {
    "status": "https://nano-seo.com/api/v1/agent/orders/0f31c8a5...",
    "report": "https://nano-seo.com/audit/0f31c8a5...",
    "report_api": "https://nano-seo.com/api/v1/audits/0f31c8a5...",
    "csv_export": "https://nano-seo.com/api/v1/audits/0f31c8a5.../export?format=csv",
    "json_export": "https://nano-seo.com/api/v1/audits/0f31c8a5.../export?format=json"
  },
  "next_action": {
    "action": "pay",
    "method": "GET",
    "status_url": "https://nano-seo.com/api/v1/agent/orders/0f31c8a5...",
    "payment_url": "https://pay.example/invoice",
    "invoice_id": "inv_example",
    "deposit_address": "nano_example",
    "deposit_tag": null,
    "amount_to_send": 0.125,
    "amount_to_send_exact": "0.125",
    "do_not_round": true,
    "currency_to_send": "XNO",
    "expires_at": "2026-11-08T12:05:00.000Z",
    "instruction": "Fetch this status again immediately before sending. Send exactly 0.125 XNO."
  },
  "polling": {
    "interval_seconds": 3,
    "stop_when": ["complete", "failed"],
    "stop_when_actions": ["contact_support", "fetch_report"]
  },
  "created_at": "2026-11-08T12:00:00.000Z",
  "updated_at": "2026-11-08T12:00:00.000Z"
}

Example response only. Live prices, addresses, IDs and amounts come from the API. Never send price_amount as crypto.

Endpoints

The whole contract.

All agent responses are JSON except report exports. Agent routes send cache-control: no-store, permissive CORS headers, and a 405 with an Allow header for an unsupported method. CORS preflight returns 204 for a supported requested method and 405 when Access-Control-Request-Method is not allowed.

GET/api/v1/agent

Manifest with endpoints, defaults, payment rules, idempotency rules, limits and retention. 200, 405, 500.

GET/api/v1/agent/openapi

OpenAPI 3.1 specification for every documented route and schema. 200, 405, 500.

GET/api/v1/agent/plans

Active plans, prices, page limits, capabilities and categories. 200, 405, 500.

POST/api/v1/agent/orders

Create an order and a server-side NanSwap payment request. 201 for a new order, 200 for an idempotent replay. Also 400, 409, 500, 502, 503.

GET/api/v1/agent/orders/{order_id}

Refresh payment state and return the next required action. 200, 400 for a malformed ID, 404, 405, 500.

GET/api/v1/audits/{order_id}

Return the completed report JSON. 404 before the audit starts, 409 while it is running, 410 after the 14-day retention window. Also 405, 500.

GET/api/v1/audits/{order_id}/export?format=csv|json

Download the report as text/csv or an exported JSON document. Unknown formats return 400; report states match the report endpoint.

POST/api/v1/demo/pay

Available only when the deployment enables demo payments. When live NanSwap payments are enabled this route returns 404.

Errors and status codes

Every failure has a predictable shape.

Agent routes return { "error": "message" } for every non-2xx response. Errors keep CORS headers and cache-control: no-store. Treat 4xx as a request problem. Retry 502 and 500 with backoff; 503 requires a configuration fix.

Error responseapplication/json
{ "error": "Order not found." }
StatusMeaningWhat to do
200Success, or an idempotent replay.Read the body. A replay also sends Idempotency-Replayed: true.
201Order created.Read next_action and save order_id. The Location header points at the status URL.
204CORS preflight success.No body.
400Invalid JSON, missing required field, invalid URL, invalid idempotency key, or a payment request rejected by NanSwap.Fix the request before retrying.
404Order, audit or route not found; demo payments disabled.Check the ID and environment. Do not retry blindly.
405Unsupported HTTP method.Read the Allow header.
409Idempotency key reused for a different request, or the audit is still running.Reuse the original request or poll the status URL.
410The report expired after 14 days and its detailed data was purged.Export reports before expiry. Start a new audit if needed.
500Unexpected server error.Retry with backoff and include the order ID when contacting support.
502The payment provider is unavailable or returned an unusable response.Retry with backoff; do not send funds until the status endpoint returns usable instructions.
503NanSwap Pay is not configured on this deployment.Contact support or use demo mode when it is available.

Payment lifecycle

How NanSwap Pay fits in.

Agent orders deliberately use NanSwap's server API rather than the website iframe. The agent receives payment fields it can act on directly.

  1. 01

    Create the order

    nanoSEO creates a unique order ID and asks NanSwap Pay for an invoice. Save the order_id and urls.status immediately.

  2. 02

    Pay with the returned instructions

    Fetch the status again immediately before paying. Use payment.payment_url when supplied, or send next_action.amount_to_send_exact in next_action.currency_to_send to deposit_address. Do not round or convert it, and include deposit_tag when present. Never send price_amount or amount as crypto.

  3. 03

    Poll the status URL

    The status endpoint refreshes the invoice with NanSwap. Poll every 3 seconds while polling is present. A qualifying payment changes the order to paid and starts the audit. Stop on complete, failed, or when next_action.action is contact_support, then open next_action.contact_url.

  4. 04

    Fetch and export the report

    When status is complete, fetch next_action.url or use the CSV/JSON export endpoint. Reports and their detailed page data are deleted 14 days after completion; after that the API returns 410.

Request contract

Only three fields are required.

Use automatic discovery for the normal case, or provide exact URLs for a controlled review. Manual selections must share the target site's origin and stay within the plan's page limit. Unknown top-level fields are ignored.

FieldRequiredNotes
package_idYesTake a paid ID from /api/v1/agent/plans. Missing or inactive packages are rejected with 400. The Free Daily Check is website-only.
target_urlYesPublic HTTP or HTTPS URL. Private and internal hosts and URL credentials are rejected.
terms_acceptedYesMust be true; confirms acceptance of the Terms of Use and Privacy Policy.
category_idNoDefaults to general. Must be an active category from the catalog. Case-insensitive.
scan_modeNoauto (default) uses the sitemap and internal links. manual uses selected_urls. Case-insensitive.
selected_urlsManual onlyAt least one same-origin URL, up to the selected plan limit and at most 25.
discount_codeNoOptional coupon code up to 24 characters; invalid or expired codes are rejected. Case-insensitive.
payin_currencyNoNanSwap currency code such as XNO, BAN, BTC, or ETH. Case-insensitive. Defaults to the deployment default, normally XNO.
idempotency_keyNoBody alternative to the header. 8–128 printable ASCII characters, no spaces; surrounding whitespace is trimmed. The Idempotency-Key header wins when both are present.
Idempotency-KeyHeader, recommendedUnique per intended order and reused for every retry. Identical requests without one are deduplicated only within the same 10-minute window.

Plans

Different reports, not the same page count.

Spot Check is a focused page audit. Site Audit adds site-wide discovery, duplicate checks and page comparison. Deep Audit adds an internal-link map, orphan pages, sitemap gaps and a priority roadmap.

Spot CheckLive price1 page · focused fixes
Site AuditLive priceUp to 10 · site-wide checks
Deep AuditLive priceUp to 25 · roadmap + link map

Prices and availability are authoritative at GET /api/v1/agent/plans. Payments are in USD-equivalent crypto through NanSwap.

Contact

Order, report or integration help.

Start with the manifest and OpenAPI file. If an order needs investigating, include the order ID and the exact response you received. Use the contact page for orders, reports, privacy and legal requests.