walletlink.social

Resolve one or more Ethereum addresses to the social identities attached to them: X handle, Farcaster account, ENS name, Lens profile, GitHub account. COST: one match credit per address that resolves to an X handle or a Farcaster account. An address that resolves to nothing is free, and so is one carrying only an ENS name, a Lens profile or a GitHub account. Up to 50 addresses per call on the default plan; a live Scale pack raises the ceiling to 200 and Index to 1000, and the API refuses over YOUR ceiling with BATCH_SIZE_EXCEEDED naming it. A batch call spends one request-unit per address of the per-minute window, and a full batch fills most of a minute on every plan: the default plan gives 60 units per minute and 50-address batches, and a live Scale or Index pack raises both. Pace multi-batch runs a minute apart and read the reset time from the quota. Each identity reports whether the address owner attested it rather than it being correlated by a third party, and each X handle reports whether it still reaches anyone: a handle can be attested and suspended, or freed and since taken by a stranger. Send every address you need in one call. Duplicates are removed before you are charged, but each copy still costs throughput. A retried call bills again: duplicates are removed inside one call, never across calls, and a tool call cannot carry an idempotency key. Before resending a call that may have gone through, read the balance instead of guessing.

{
  "type": "object",
  "properties": {
    "addresses": {
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[a-fA-F0-9]{40}$"
      },
      "description": "Ethereum addresses, each 0x followed by 40 hex characters. Case does not matter."
    }
  },
  "required": [
    "addresses"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find the wallets in the index attested to an X account. The reverse of resolving an address. Only wallets whose recorded sources are all attested come back, so a wallet whose attested link sits beside a correlated source is left out; resolving that address still shows it, labeled. Needs a key that belongs to an account: a key bought with USDC alone gets ACCOUNT_REQUIRED. COST: one match credit per wallet returned, and a page holds up to 100. A handle nobody holds returns an empty list and is free. The free allowance is 100 matches per 30 days, so a single widely held handle can spend all of it in one call. Check the balance first with walletlink_account_balance if that matters. A retried call bills its returned wallets again. Results are ordered by Farcaster follower count, highest first. When more_pages is true, pass next_cursor back to continue.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "pattern": "^@?[a-zA-Z0-9_]{1,15}$",
      "description": "An X handle, 1 to 15 letters, numbers or underscores. A leading @ is accepted. Case does not matter."
    },
    "cursor": {
      "description": "The next_cursor from a previous call, passed back unchanged. Omit for the first page.",
      "type": "string"
    }
  },
  "required": [
    "handle"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find the wallets in the index attested to a Farcaster account. Only wallets whose recorded sources are all attested come back, so a wallet whose Farcaster verification sits beside a correlated source is left out; resolving that address still shows it, labeled. Needs a key that belongs to an account: a key bought with USDC alone gets ACCOUNT_REQUIRED. COST: one match credit per wallet returned, and a page holds up to 100. A username nobody holds returns an empty list and is free. A retried call bills its returned wallets again. Pass the username whole, including any .eth suffix: an ENS name attached to a Farcaster account is a large share of the index, and stripping the suffix will find nothing. Results are ordered by follower count, highest first.

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,31}$",
      "description": "A Farcaster username, such as dwr or vitalik.eth. 1 to 32 characters of letters, numbers, dots and hyphens, starting with a letter or a number."
    },
    "cursor": {
      "description": "The next_cursor from a previous call, passed back unchanged. Omit for the first page.",
      "type": "string"
    }
  },
  "required": [
    "username"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

How much of the index carries each identity type. Use it to judge whether a lookup is worth making before making it. COST: free on both meters. It resolves no wallet and consumes no rate limit. A key whose balance is zero can still read the free endpoints; the balance and coverage reads keep answering at zero, and only a call that could bill refuses with NO_CREDITS. addresses_with_an_identity over addresses_checked is the coverage rate. The second number is larger because it counts addresses we have looked at and found bare. The counts are refreshed daily rather than counted live; as_of says when they were taken, and asking twice in a day returns the same numbers.

{
  "type": "object",
  "properties": {}
}

How many match credits the configured key has left, and how much of the request allowance it has used. COST: free on both meters. Call it before a reverse lookup, which can spend up to 100 credits in one go. matches_available is the meter that stops a metered call: at zero, the resolve and reverse tools refuse, while this tool and the coverage tool keep answering, so a drained key can always read its own meter. rate_limit_units_used is a separate count of requests and is not a credit figure. unmetered is true on an account that is never debited. Its matches_available is null because it has no balance to report, not because the balance is zero.

{
  "type": "object",
  "properties": {}
}

Submit a list of addresses as a background job. A job runs a deeper scan than the resolve tool: an address the index has not checked, or holds only stale answers for, is resolved against live sources, so a job can find identities the resolve tool reports as never seen. Use it for lists larger than one resolve call, or when misses are worth re-checking. COST: billed on matches exactly like resolving, when the job completes: one match credit per address that resolved to an X handle or a Farcaster account, misses free. One job may be active per account at a time; a second submission is refused until the first finishes, and the refusal names the active job id. A submission is capped at 10 times the match balance, so the worst case is bounded by what the account already holds. Submitting itself spends one request-unit of the rate window. The submission returns a job id. Poll walletlink_job_status for progress and, on completion, the results. A job that fails is never billed. Resubmitting the same list after a job completes runs the whole job again and bills its matches again.

{
  "type": "object",
  "properties": {
    "addresses": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[a-fA-F0-9]{40}$"
      },
      "description": "Ethereum addresses, each 0x followed by 40 hex characters. Case does not matter. The ceiling is the balance-derived cap, not a fixed number; a list over the cap is refused with the cap named."
    }
  },
  "required": [
    "addresses"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Progress and results for a job submitted with walletlink_submit_job. While the job runs it reports processed counts; on completion it reports the resolved records and what was billed. COST: free on both meters, so a drained key can still collect results it already paid for. A field that is absent was not measured. Absent is not false: a missing reachability means the handle was not checked, never that nobody is behind it. Only jobs submitted by this account are visible; any other id answers not found.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "The job id returned by walletlink_submit_job."
    },
    "offset": {
      "description": "Result row to start from, for a completed job. Pass the next_offset from a previous call to continue. Omit for the first page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "job_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

A dry run over a list of addresses: how many are in the index, how many were checked and found bare, how many have never been seen, and the band a resolve would bill inside. Counts only, no identities. Use it to decide whether a list is worth resolving, and which tool to spend on. COST: free on the match meter, always, even at zero balance. It weighs the rate window exactly like resolving the same list (one request-unit per address), so it previews a batch at the batch’s own pace. Minimum 10 distinct addresses, because the counts are aggregates by design; the ceiling is your plan’s batch ceiling. Reading the band: low is exact for resolving this list now (the addresses already holding an X handle or a Farcaster account). high adds never-checked addresses at the measured overall rate; a background job resolves those against live sources, a plain resolve does not. Match rates differ several-fold by chain; the coverage tool and /v1/stats carry the measured per-chain table.

{
  "type": "object",
  "properties": {
    "addresses": {
      "minItems": 10,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[a-fA-F0-9]{40}$"
      },
      "description": "Ethereum addresses, each 0x followed by 40 hex characters. Case does not matter."
    }
  },
  "required": [
    "addresses"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}