> For the complete documentation index, see [llms.txt](https://docs.yellow.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yellow.pro/api-and-programmatic-access/getting-started-with-api.md).

# Getting Started with API

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

{% hint style="info" %}
All trading, account, and transfer endpoints require authentication. Market data endpoints are public and need no credentials.
{% endhint %}

For API base URLs, see [Base URLs](/api-and-programmatic-access/overview.md#base-urls).

## Authentication Flow

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

{% stepper %}
{% step %}

### Request a challenge

POST to `/auth/challenge` with your wallet address.
{% endstep %}

{% step %}

### Sign the challenge

Sign the returned challenge text with your Ethereum wallet.
{% endstep %}

{% step %}

### Verify the signature

POST to `/auth/verify` with your wallet address, the challenge, and the signature.
{% endstep %}

{% step %}

### Receive tokens

Get a JWT access token and a refresh token for API access.
{% endstep %}

{% step %}

### Use the access token

Include the JWT in the `Authorization` header on authenticated endpoints.

```http
Authorization: Bearer <your-jwt-token>
```

{% endstep %}
{% endstepper %}

See the [Authentication Service API](/api-and-programmatic-access/authentication-service-api.md) for full request and response details on each endpoint.

## Authentication Methods

All authenticated endpoints support two authentication methods.

{% tabs %}
{% tab title="JWT Token" %}
Obtained via the `/auth/verify` endpoint. Include the token in the `Authorization` header:

```http
Authorization: Bearer <token>
```

Supported by all authenticated endpoints.
{% endtab %}

{% tab title="API Key (HMAC)" %}
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:

```http
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**](/api-and-programmatic-access/signing-requests-with-api-keys.md) for the exact signature algorithm and ready-to-use Node.js and Python examples.

{% hint style="danger" %}
Never commit API keys or secrets to version control. Store them in environment variables or a secrets manager.
{% endhint %}
{% endtab %}
{% endtabs %}

## Security Notes

{% hint style="warning" %}

* 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
  {% endhint %}

## Next Steps

<a href="/pages/Z3MLvjXcrYgvwXhep5Zt" class="button primary" data-icon="key">Create an API key</a>

| Section                            | Description                               | Target                                                                                           |
| ---------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **API Key Management**             | Create, list, and revoke API keys         | [API Key Management](/api-and-programmatic-access/api-key-management.md)                         |
| **Signing Requests with API Keys** | HMAC-SHA256 signing with code examples    | [Signing Requests with API Keys](/api-and-programmatic-access/signing-requests-with-api-keys.md) |
| **Market Data API**                | Prices and indicators (no auth required)  | [Market Data API](/api-and-programmatic-access/market-data-api.md)                               |
| **Spot Trading**                   | Place and manage spot orders              | [Spot Trading API](/api-and-programmatic-access/spot-trading-api.md)                             |
| **Perpetuals Trading**             | Positions, leverage, and perpetual orders | [Perpetuals Trading API](/api-and-programmatic-access/perpetuals-trading-api.md)                 |