Social verification

client.socialVerification proves that the authenticated caller controls an external social account. Every method is authenticated. These calls need a wallet session. An API key gets AuthenticationError.

start begins or restarts verification, and get reports the current status, attempts, and any last error. For Twitter, provide a handle and place the returned poly_... code in the selected profile location, then call markReady to queue the check. For Discord, omit the handle: the authenticated bot supplies the provider identity. Discord supports "channel" and "dm" methods and defaults to "channel"; it can return an empty challengeCode when no new challenge is issued.

Methods

start(input, options?)

Begins or restarts verification and returns the challengeCode, its expiresAt (about 15 minutes out), and the current verification record. Twitter trims whitespace and strips leading @ characters from its required handle. Discord does not accept a handle.

const { challengeCode, expiresAt } = await client.socialVerification.start({
	provider: "twitter",
	handle: "@satoshi", // stored as "satoshi"
	method: "profile", // optional, defaults to "profile"
});

// Tell the user to place challengeCode in the Twitter profile before it expires.
console.log(challengeCode); // "poly_..."

For Discord, let the SDK use the provider default or choose one of its supported methods:

const { challengeCode } = await client.socialVerification.start({
	provider: "discord",
	method: "channel",
});

StartVerificationInput

Twitter handles must contain 1 to 15 ASCII letters, digits, or underscores. Twitter accepts only the "profile" method. Discord accepts only "channel" or "dm" and supplies its identity through the authenticated bot.

markReady(input, options?)

Queues the provider check after the caller has placed the challenge code. Returns the updated verification record. Call this once the code is live at the location the method requires.

const { verification } = await client.socialVerification.markReady({ provider: "twitter" });
console.log(verification?.status); // e.g. "queued"

get(input, options?)

Returns the caller's current verification state for a provider: status, challenge metadata, attempts, lastError, errorCode, and the verifiedAt timestamp once it succeeds.

const { verification } = await client.socialVerification.get({ provider: "twitter" });
if (verification?.status === "verified") {
	console.log("verified at", verification.verifiedAt);
} else if (verification?.errorCode === "social_account_already_linked") {
	// Final for this account: point the user to the account already linked to this identity.
} else if (verification?.status === "failed") {
	console.error(verification.lastError);
}

status is one of "pending_user_action", "queued", "in_progress", "verified", "failed", "expired", or "canceled". Poll get after markReady until the status settles.

errorCode is the machine-readable failure for the current state, such as "social_account_already_linked". It is "unspecified" when no typed failure applies or the code is newer than the SDK. Branch on errorCode, not on the lastError text.

Already linked identities

A social identity can be linked to only one Polyester account. When it is already linked to another account, the verification reports errorCode: "social_account_already_linked", and calls rejected for that reason throw the non-retryable AlreadyExistsError with detail.code === "AUTH_SOCIAL_ACCOUNT_ALREADY_LINKED". Treat it as final for the current account: direct the user to the Polyester account already linked to that identity instead of restarting verification.

Related

• Profile for the account identity these handles attach to.
• Daily claims, which need a verified Twitter (X) or Discord account.
• Errors for the error type reference.

Related Topics