> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yellow.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting your credentials

> How to obtain the API key, secret, and app session id the MCP server needs for account and trading tools.

Market data needs no credentials. Everything account-related needs all three of `YELLOW_PRO_API_KEY`, `YELLOW_PRO_API_SECRET`, and `YELLOW_PRO_APP_SESSION_ID`.

<Warning>
  The MCP server cannot create these for you. EIP-191 wallet signing and JWT authentication are deliberately not implemented in the server, so you obtain the key through the REST API (or the Yellow\.pro web UI) before configuring the MCP.
</Warning>

## Creating an API key

The API key flow authenticates your wallet, exchanges the signature for a JWT, then uses that JWT to mint a key.

<Steps>
  <Step title="Request a challenge">
    `POST /auth/challenge` returns a challenge string to sign. See the [Authentication Service API](/api-and-programmatic-access/authentication-service-api).
  </Step>

  <Step title="Sign the challenge with your wallet">
    Sign the returned message with the wallet that owns the account. This is the EIP-191 step the MCP does not perform.
  </Step>

  <Step title="Exchange the signature for a JWT">
    `POST /auth/verify` returns a session and a JWT for the authenticated wallet.
  </Step>

  <Step title="Create the API key">
    `POST /accounts/api-keys`, authenticated with that JWT, returns the key and secret. See [API Key Management](/api-and-programmatic-access/api-key-management).

    <Warning>
      The secret is returned **once** and cannot be retrieved afterwards. Store it before closing the response. If you lose it, revoke the key and create a new one.
    </Warning>
  </Step>
</Steps>

You can also create and revoke keys from the web UI under **Settings → API Keys → Manage**.

## The app session id

`YELLOW_PRO_APP_SESSION_ID` is required for every private request and is included in the request signature, so no account or trading tool works without it.

<Info>
  A session identifier is returned by `POST /auth/verify` and surfaced by `GET /auth/me`. If you are unsure which value belongs in this variable, or whether yours has expired, contact [support](/community-and-resources/contact-support) rather than guessing — a wrong or stale value fails every private call.
</Info>

## Scopes and tools

API keys carry scopes. Granting only what you need avoids a class of `403` responses and limits the damage if a config file leaks.

| Scope           | Needed for                                                                 |
| --------------- | -------------------------------------------------------------------------- |
| `read:spot`     | Spot balances, spot accounts, open orders, order history, fills, fee rates |
| `trade:spot`    | Placing and cancelling spot orders                                         |
| `read:futures`  | Perpetual positions, orders, position history, funding payments            |
| `trade:futures` | Perpetual orders, closing positions, changing leverage                     |
| `withdraw:spot` | **Not needed.** The MCP exposes no withdrawal tool.                        |

<Tip>
  Because the server has no withdrawal tool at all, a key without `withdraw:spot` cannot move funds off the exchange no matter what an agent asks for. Leave that scope off.
</Tip>

If a tool returns a permission error, check the key's scopes before anything else. See [Troubleshooting](/mcp/troubleshooting).

## Environments

Credentials are environment-specific: keys created against production do not work against staging, and vice versa.

<Warning>
  There is currently no documented route to obtain a staging account or staging API keys. If you need to rehearse against staging, ask [support](/community-and-resources/contact-support) first — otherwise plan to test on production with small sizes and trading disabled.
</Warning>

## Where credentials are stored

Credentials are sent only to the Yellow\.pro API, but the setup helpers write them to disk in cleartext:

* `claude mcp add -s user` writes the key and secret to `~/.claude.json`
* `yellow-pro setup openclaw` writes them to `~/.openclaw/openclaw.json`
* The one-line installer places them in your shell history

Treat those files as secrets. If one leaks, revoke the key immediately via `POST /accounts/api-keys` revocation or the web UI, then issue a new one.