Skip to main content

​
Overview

The Membership API allows users to connect their wallets (EVM, Solana, or TON) and become members of Turtle. This API follows a secure three-step flow to ensure wallet ownership verification.

​
Authentication Flow

1

Check Membership Status

Verify if a wallet address is already associated with a Turtle account
2

Request Signature Agreement

Generate a message that must be signed by the wallet to prove ownership
3

Create Membership

Submit the signed message to create a new user account and associate the wallet

​
Endpoints

​
Check Membership Status

curl -X GET "https://earn.turtle.xyz/v1/membership?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm"
Query Parameters
​
address
string
required
The wallet address to check
​
walletEcosystem
string
default:"evm"
The blockchain ecosystem. Supported values: evm, solana, ton
Response 
{
  "isMember": false
}

​
Request Signature Agreement

curl -X POST https://earn.turtle.xyz/v1/membership/agreement \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "url": "https://turtle.xyz",
    "chainId": "1"
  }'
Request Body
​
address
string
required
The wallet address requesting membership
​
walletEcosystem
string
required
The blockchain ecosystem. Supported values: evm, solana, ton
​
url
string
required
The URL of the application (used in the signature message)
​
chainId
string
default:"1"
The chain ID for EVM wallets. Not required for Solana or TON
Response 
{
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "message": "turtle.xyz wants you to sign in with your Ethereum account:\n0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D\n\nSign Up to Turtle\n\nURI: https://turtle.xyz\nVersion: 1\nChain ID: 1\nNonce: 550e8400-e29b-41d4-a716-446655440000\nIssued At: 2024-01-15T10:00:00Z"
}

​
Create Membership

curl -X POST https://earn.turtle.xyz/v1/membership \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "signature": "0x1234567890abcdef...",
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "distributorId": "your-distributor-id"
  }'
Request Body
​
address
string
required
The wallet address creating the membership
​
walletEcosystem
string
required
The blockchain ecosystem. Supported values: evm, solana, ton
​
signature
string
required
The signature of the message returned by the agreement endpoint
​
nonce
string
required
The nonce returned by the agreement endpoint
​
distributorId
string
The distributor ID to associate the membership with. When provided, the user will be tracked as having signed up through the distributor’s integration.
Response 
{
  "isMember": true,
  "error": ""
}

​
Complete Flow Example

Here’s a complete example of the membership creation flow: 
# Step 1: Check if wallet is already a member
curl -X GET "https://earn.turtle.xyz/v1/membership?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm"
# Response: {"isMember": false}

# Step 2: Request signature agreement
curl -X POST https://earn.turtle.xyz/v1/membership/agreement \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "url": "https://turtle.xyz",
    "chainId": "1"
  }'
# Response: {"nonce": "550e8400...", "message": "turtle.xyz wants you to sign..."}

# Step 3: Sign the message with your wallet (using web3 library or wallet app)
# This step happens client-side

# Step 4: Submit the signature to create membership
curl -X POST https://earn.turtle.xyz/v1/membership \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "signature": "0x1234567890abcdef...",
    "nonce": "550e8400-e29b-41d4-a716-446655440000"
  }'
# Response: {"isMember": true, "error": ""}

# Step 5: Verify membership was created
curl -X GET "https://earn.turtle.xyz/v1/membership?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm"
# Response: {"isMember": true}

​
Error Handling

​
Common Errors

Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid wallet ecosystem"
  }
}
Solution: Use one of the supported ecosystems: evm, solana, or ton
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid wallet address"
  }
}
Solution: Ensure the wallet address is valid for the specified ecosystem
Status Code: 409 ConflictResponse:
{
  "error": {
    "status": "ALREADY_EXISTS",
    "error": "wallet already exists"
  }
}
Solution: This wallet is already associated with an account. Is not necessary to create a new membership.
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid nonce or expired"
  }
}
Solution: Request a new agreement and sign it promptly. Nonces expire after a short period

​
Security Considerations

Never share your private keys or seed phrases. The API only requires signatures, not private keys.
  • Nonces are single-use and expire after a short period
  • Messages follow the EIP-4361 standard for EVM wallets
  • All signatures are verified server-side before creating accounts