// Works directly from any browser or frontend app
const response = await fetch(
  "https://developer.worldscore.world/api/v1/score?wallet=0x...",
  { headers: { "X-API-Key": "ws_live_your_key" } }
);

const response = await fetch(
  `https://developer.worldscore.world/api/v1/score?wallet=${userWallet}`,
  { headers: { "X-API-Key": "ws_live_your_key" } }
);
const { data } = await response.json();

if (data === null) {
  // User not found — show a "Verify on WorldScore" prompt
  showVerificationPrompt();
} else {
  // User found — use their score
  console.log("Score:", data.totalScore);
  console.log("Level:", data.verificationLevel);
}

<!-- HTML example for your mini app -->
<div class="verify-prompt">
  <h3>Get Your WorldScore</h3>
  <p>Verify your identity on WorldScore to access premium features.</p>
  
  <!-- Universal Link (works everywhere — recommended) -->
  <a href="https://world.org/mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451"
     class="verify-button">
    Verify on WorldScore →
  </a>
</div>

// JavaScript — redirect user to WorldScore
function redirectToWorldScore() {
  // Universal Link — works everywhere (recommended)
  window.location.href = 
    "https://world.org/mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451";
}

// React component example
function VerifyPrompt() {
  return (
    <div className="verify-card">
      <h3>Get Verified on WorldScore</h3>
      <p>Complete your verification to unlock features.</p>
      <a 
        href="https://world.org/mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451"
        className="verify-btn"
      >
        Open WorldScore →
      </a>
    </div>
  );
}

<!-- Inside a World Mini App (use deep link for instant navigation) -->
<a href="worldapp://mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451">
  Get Your WorldScore
</a>

<!-- For web apps or external sites (use universal link) -->
<a href="https://world.org/mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451"
   target="_blank">
  Verify on WorldScore
</a>

async function getWorldScore(walletAddress) {
  const response = await fetch(
    `https://developer.worldscore.world/api/v1/score?wallet=${walletAddress}`,
    { headers: { "X-API-Key": "ws_live_your_api_key_here" } }
  );

  const { success, data, message } = await response.json();

  if (!success) {
    throw new Error("API request failed");
  }

  if (data === null) {
    // User not registered on WorldScore
    return {
      found: false,
      // Redirect user to WorldScore app to get verified
      verifyUrl: "https://world.org/mini-app?app_id=app_fa8974b2c77a879724c770556d4a9451"
    };
  }

  return {
    found: true,
    score: data.totalScore,
    level: data.verificationLevel,
    orbVerified: data.credentials.orbVerified,
    breakdown: data.scoreBreakdown,
  };
}

// Usage
const result = await getWorldScore("0x1234...abcd");
if (!result.found) {
  // Show: "Verify on WorldScore to continue"
  window.location.href = result.verifyUrl;
} else if (result.score >= 600) {
  // Grant access to premium features
}

import requests

def get_worldscore(wallet_address, api_key):
    response = requests.get(
        "https://developer.worldscore.world/api/v1/score",
        params={"wallet": wallet_address},
        headers={"X-API-Key": api_key}
    )
    result = response.json()

    if not result.get("success"):
        raise Exception("API request failed")

    data = result.get("data")
    if data is None:
        return {"found": False, "message": "User not on WorldScore"}

    return {
        "found": True,
        "score": data["totalScore"],
        "level": data["verificationLevel"],
        "orb_verified": data["credentials"]["orbVerified"],
    }

# Usage
score_data = get_worldscore("0x1234...abcd", "ws_live_your_key")
if not score_data["found"]:
    print("User needs to verify on WorldScore first")
elif score_data["score"] >= 700:
    print(f"High trust user: {score_data['score']}")

# Full score lookup
curl -X GET \
  "https://developer.worldscore.world/api/v1/score?wallet=0x1234...abcd" \
  -H "X-API-Key: ws_live_your_api_key_here"

# Quick verification check
curl -X GET \
  "https://developer.worldscore.world/api/v1/verify?wallet=0x1234...abcd" \
  -H "X-API-Key: ws_live_your_api_key_here"

# Public stats (no API key needed)
curl https://developer.worldscore.world/api/v1/stats

// Error response format
{
  "error": "API key required",
  "message": "Include your API key in the X-API-Key header or as api_key query parameter"
}

// Robust error handling example
async function safeScoreLookup(wallet, apiKey) {
  try {
    const res = await fetch(
      `https://developer.worldscore.world/api/v1/score?wallet=${wallet}`,
      { headers: { "X-API-Key": apiKey } }
    );

    if (res.status === 429) {
      const retryAfter = res.headers.get("X-RateLimit-Reset");
      console.warn("Rate limited, retry after:", retryAfter);
      return null;
    }

    if (!res.ok) {
      const err = await res.json();
      throw new Error(err.error || "Unknown error");
    }

    return await res.json();
  } catch (error) {
    console.error("WorldScore API error:", error.message);
    return null;
  }
}