Starter Grant

New wallets start with no native COTI, which means they cannot pay gas for their first transaction. The starter grant flow provides a one-time onboarding grant for eligible wallets.

Overview

The starter grant is handled through an external service that works with the private messaging SDK and MCP server.

• each wallet can claim only once

• the flow is challenge-based

• the challenge is intentionally lightweight

• the SDK can complete the full request-and-claim cycle in one call

Quick flow

The recommended path is requestStarterGrant().

The SDK-level starter-grant helpers default to the deployed service, so url is optional unless you want to override it:

import { requestStarterGrant } from "@coti-io/coti-sdk-private-messaging";

const claimA = await requestStarterGrant(client);

const claimB = await requestStarterGrant(client, {
  timeoutMs: 20000
});

const result = await requestStarterGrant(client, {
  url: "http://other-service:8787",
  timeoutMs: 15000
});

This helper:

1. requests a challenge

2. solves the lightweight prompt

3. signs the claim payload with the configured wallet

4. submits the final claim

The result includes:

• status

• walletAddress

• transactionHash

• amountWei

• prompt

• expiresAt

Manual flow

If you want tighter control over the onboarding sequence, use the three-step flow:

import {
  getStarterGrantStatus,
  getStarterGrantChallenge,
  claimStarterGrant
} from "@coti-io/coti-sdk-private-messaging";

1. Call getStarterGrantStatus() to check whether the wallet is eligible, challenge_pending, or claimed.

2. Call getStarterGrantChallenge() to receive challengeId, prompt, claimPayload, and expiresAt.

3. Call claimStarterGrant() with challengeId, challengeAnswer, and claimPayload.

Service configuration

The starter grant helpers can use the deployed default service with no explicit configuration:

await requestStarterGrant(client);

You can also pass optional overrides:

• authToken

• installIdPath

• timeoutMs

• url

Use url only when you want to override the default deployed service.

For MCP server deployments, the matching environment variables are:

• STARTER_GRANT_SERVICE_URL

• STARTER_GRANT_SERVICE_TIMEOUT_MS

• STARTER_GRANT_SERVICE_AUTH_TOKEN

• STARTER_GRANT_INSTALL_ID_PATH

Common failures

Typical failures include:

• the starter grant service is not configured

• the wallet has already claimed the one-time grant

• the challenge expired before it was submitted

• the local install ID state is missing or inconsistent

Important notes

• the grant is one-time per wallet address

• the wallet must exist before the claim flow starts

• the service uses an install ID as a soft local deduplication signal

• after a successful claim, the wallet usually has enough COTI for initial testnet activity such as messaging and contract interaction