API Keys - Turtle Docs

Every Earn API endpoint requires an API key, passed on the X-API-Key header. Use the key issued when your organization was created, or contact the Turtle team if you need one. Store it securely.

Key types

There are two key types, distinguished by prefix. The publishable key (pk_live_) is safe in client-side and browser code. It covers read access to opportunities, deposit and wallet activity, and the verify endpoint. The secret key (sk_live_) is server-side only. It is required for write operations such as generating deposit and withdrawal transactions, creating memberships, and managing streams.

Never expose your sk_live_ key in client-side code, browsers, or public repositories. Treat it like a database password.

Publishable key

curl https://earn.turtle.xyz/v2/opportunities/ \
  -H "X-API-Key: pk_live_xxxxx"

const res = await fetch('https://earn.turtle.xyz/v2/opportunities/', {
  headers: { 'X-API-Key': 'pk_live_xxxxx' },
});

Secret key

Use this from your backend only. The example below builds a deposit, a write action that the publishable key cannot perform. See Deposit for the full request and response.

curl -X POST "https://earn.turtle.xyz/v2/actions/deposit/{opportunityId}" \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "userAddress": "0x1234...", "tokenIn": "0xA0b8...", "amount": "1000000", "distributorId": "your-distributor-id", "mode": "direct" }'

const res = await fetch(
  `https://earn.turtle.xyz/v2/actions/deposit/${opportunityId}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TURTLE_SECRET_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      userAddress: '0x1234...',
      tokenIn: '0xA0b8...',
      amount: '1000000',
      distributorId: 'your-distributor-id',
      mode: 'direct',
    }),
  }
);

Rate limits

Rate limit state is returned in response headers. The budget is per key and resets hourly.

Header	Description
`X-RateLimit-Limit`	Hourly cost unit budget
`X-RateLimit-Remaining`	Cost units remaining this hour
`X-RateLimit-Used`	Cost units consumed this hour
`X-Monthly-Limit`	Monthly cost unit cap, if configured
`X-Monthly-Usage`	Cost units consumed this month
`X-Monthly-Remaining`	Cost units remaining this month

When a limit is exceeded, the API returns 429 Too Many Requests.

Next steps

A valid key is only half of access control. Action endpoints also require the user’s wallet to be a registered Turtle member. See Register Wallet for the membership flow.

​Key types

​Publishable key

​Secret key

​Rate limits

​Next steps

Key types

Publishable key

Secret key

Rate limits

Next steps