Available Scopes

Scopes define what permissions your application requests from users during OAuth2 authorization.

Supported Scopes

payments:sign

payments:sign

Description: Sign X402 payment proofs on behalf of the user.

Allows:

• Signing payments within user-defined spending limits
• Using the /api/sign-payment endpoint
• Using the /api/x402/fetch proxy
• Accessing the AI Gateway (/v1/chat/completions)

Does not allow:

• Exceeding spending limits
• Transferring funds directly
• Modifying wallet settings

balance:read

balance:read

Description: View the user's USDC balance.

Allows:

• Reading wallet balance via /api/balance
• Viewing balance across networks

Does not allow:

• Modifying balance
• Initiating transfers

Default Scopes

If no scope is specified in the authorization request, these scopes are used:

payments:sign balance:read

Requesting Scopes

Include scopes in your authorization URL:

https://api.agnic.ai/oauth/authorize?
  client_id=your-app
  &redirect_uri=https://yourapp.com/callback
  &state=random_state
  &response_type=code
  &scope=payments:sign+balance:read

Scope Inheritance

When a user re-authorizes your app:

• If requested scopes are a subset of previously granted scopes, authorization is automatic
• If you request new scopes, the user sees the consent screen again

Checking Granted Scopes

The token response includes the granted scopes:

{
  "access_token": "agnic_at_abc123...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "payments:sign balance:read"
}

Always check that your required scopes were granted before using the token.

Future Scopes

Additional scopes may be added in the future:

Best Practices

1. Request minimal scopes - Only ask for what you need
2. Explain scope usage - Tell users why you need each permission
3. Handle scope changes - Be prepared for users to deny certain scopes
4. Check granted scopes - Verify the token has required permissions

Next Steps