Getting Started with API

This guide walks you through authenticating with the Yellow.pro API so you can start calling endpoints.

All trading, account, and transfer endpoints require authentication. Market data endpoints are public and need no credentials.

For API base URLs, see Base URLs.

Authentication Flow

Yellow.pro uses Ethereum wallet-based authentication with a challenge-response mechanism:

Request a challenge

POST to /auth/challenge with your wallet address.

Sign the challenge

Sign the returned challenge text with your Ethereum wallet.

Verify the signature

POST to /auth/verify with your wallet address, the challenge, and the signature.

Receive tokens

Get a JWT access token and a refresh token for API access.

Use the access token

Include the JWT in the Authorization header on authenticated endpoints.

Authorization: Bearer <your-jwt-token>

See the Authentication Service API for full request and response details on each endpoint.

Authentication Methods

All authenticated endpoints support two authentication methods.

JWT Token
API Key (HMAC)

Obtained via the /auth/verify endpoint. Include the token in the Authorization header:

Authorization: Bearer <token>

Supported by all authenticated endpoints.

Best suited for programmatic / server-side access where you don’t want to manage a wallet signing flow on every request. Each request includes three headers:

X-API-KEY: <your-api-key>
X-TIMESTAMP: <Unix timestamp in seconds>
X-SIGNATURE: <HMAC-SHA256 signature of the request>

Supported by all authenticated endpoints (spot, perpetuals, transfers)
Automatically falls back to JWT if API key headers are not present

See Signing Requests With API Keys for the exact signature algorithm and ready-to-use Node.js and Python examples.

Never commit API keys or secrets to version control. Store them in environment variables or a secrets manager.

Security Notes

Access tokens expire in 15 minutes
Refresh tokens expire in 7 days
Sessions can be invalidated via logout
Rate limiting is enforced on authentication endpoints

Next Steps

Create an API key

Section	Description	Target
API Key Management	Create, list, and revoke API keys	API Key Management
Signing Requests with API Keys	HMAC-SHA256 signing with code examples	Signing Requests with API Keys
Market Data API	Prices and indicators (no auth required)	Market Data API
Spot Trading	Place and manage spot orders	Spot Trading API
Perpetuals Trading	Positions, leverage, and perpetual orders	Perpetuals Trading API

​Authentication Flow

​Authentication Methods

​Security Notes

​Next Steps

Authentication Flow

Authentication Methods

Security Notes

Next Steps