Authentication

SharkBlock MCP uses OAuth 2.1 with PKCE to securely authenticate AI agents. This is the same standard used by major platforms like GitHub and Google.

How It Works


AI Agent                    SharkBlock API              SharkBlock App (Privy)
   │                              │                              │
   │  1. GET /oauth/authorize     │                              │
   │  ──────────────────────►     │                              │
   │                              │  2. Redirect to login        │
   │  ◄──────────────────────     │  ──────────────────────►     │
   │                              │                              │
   │              3. User signs in with Privy                    │
   │                              │  ◄──────────────────────     │
   │                              │  4. Auth code issued         │
   │  ◄──────────────────────     │                              │
   │  5. Redirect with code       │                              │
   │                              │                              │
   │  6. POST /oauth/token        │                              │
   │  ──────────────────────►     │                              │
   │                              │  7. Verify PKCE              │
   │  ◄──────────────────────     │  8. Return JWT tokens        │
   │  Access + Refresh tokens     │                              │
   │                              │                              │
   │  9. POST /mcp (Bearer token) │                              │
   │  ──────────────────────►     │                              │
   │  ◄──────────────────────     │                              │
   │  Tool results                │                              │

OAuth 2.1 Endpoints

Endpoint	Method	Purpose
`/.well-known/oauth-protected-resource`	GET	Discover authorization server
`/oauth/.well-known/openid-configuration`	GET	OpenID Connect discovery
`/oauth/authorize`	GET	Start authorization flow
`/oauth/token`	POST	Exchange code for tokens / refresh tokens
`/oauth/callback`	POST	Internal — Privy token exchange

Discovery

MCP clients automatically discover auth configuration via the Protected Resource Metadata endpoint:


curl https://api.alpha.sharkblock.io/.well-known/oauth-protected-resource


{
  "resource": "https://api.alpha.sharkblock.io",
  "authorization_servers": ["https://api.alpha.sharkblock.io"],
  "scopes_supported": [
    "profile:read",
    "trade:execute",
    "wallet:delegate",
    "blockchain-data:read"
  ],
  "bearer_methods_supported": ["header"]
}

Scopes

Scopes control what your AI agent can access:

Scope	Access
`profile:read`	View profile, notifications, preferences, affiliations
`trade:execute`	Create/manage strategies, open/close positions, manage wallets
`wallet:delegate`	Enable/disable wallet delegation for automated trading
`blockchain-data:read`	Token prices, charts, market data, wallet analysis

Your SharkBlock account’s existing permissions determine which scopes are available.

Token Lifecycle

Access Token

Type: JWT (Bearer)
Included in: Authorization: Bearer <token> header on MCP requests
Contains: User ID, session ID, scopes

Refresh Token

Purpose: Obtain new access tokens without re-authenticating
Usage: POST /oauth/token with grant_type=refresh_token


curl -X POST https://api.alpha.sharkblock.io/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your_refresh_token"
  }'

Security Measures

PKCE (Proof Key for Code Exchange)

Every authorization request requires PKCE with the S256 method. This prevents authorization code interception attacks — even if someone captures the code, they can’t exchange it without the original code verifier.

Rate Limiting

All MCP requests are rate-limited per user:

Scope	Limit	Window
`trade:execute`	30 requests	1 minute
`blockchain-data:read`	60 requests	1 minute
`profile:read`	120 requests	1 minute
Global	200 requests	1 minute

Exceeding limits returns HTTP 429 with a resetAt timestamp.

What MCP Cannot Do

Access your private keys (managed by Privy)
Withdraw funds from your wallet
Change your login credentials
Bypass your strategy settings
Execute trades without delegation enabled

Revoking Access

To disconnect an AI agent:

The agent’s tokens will expire naturally
Do not re-authenticate when prompted
For immediate revocation, log out of your SharkBlock session

Future: A dedicated token management page will allow granular control over connected agents.