> For the complete documentation index, see [llms.txt](https://docs.prophetmarket.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.prophetmarket.ai/get-started/api/authentication.md).

# Authentication

Public market data requires no credentials. Authentication is necessary for reading account data, trading, and creating markets.

## Two Mechanisms

The API accepts two types of credentials:

| Mechanism     | Obtained by                                        | Suited to                               |
| ------------- | -------------------------------------------------- | --------------------------------------- |
| Session token | Signing in to the application                      | Browser clients, short-lived sessions   |
| HMAC key pair | Registering credentials against a signed challenge | Scripts, bots, server-side integrations |

Session tokens are supplied in the `Authorization` header.

## Registering API Credentials

Programmatic access uses a challenge-and-signature exchange to prove account ownership without transmitting the key.

1. **Request a challenge (Query)**

```graphql
query {
  generateApiChallenge {
    nonce
    timestamp
    action
    domain { name version chainId }
  }
}
```

2. **Sign and submit (Mutation)**

Assemble the response into an EIP-712 typed data structure, sign it, and submit:

```graphql
mutation Register($signature: String!, $nonce: String!, $timestamp: String!) {
  registerApiCredentials(
    signature: $signature
    nonce: $nonce
    timestamp: $timestamp
  ) {
    apiKey
    apiSecret
  }
}
```

{% hint style="danger" %}
**The API secret is shown exactly once**

Capture it immediately and store it securely. If lost, you must register new credentials.
{% endhint %}

Both calls require a valid session token to bootstrap the credentials.

## What Authentication Unlocks

* **Account Data:** Positions, balances, order history, transaction records.
* **Trading:** Placing orders requires an EIP-712 signing flow (`orderParams` -> sign -> `submitSignedOrder`). Simple order book interactions (`placeBet`, `placeOrder`) require a verified email and sufficient balance.
* **Market Creation:** A multi-step process (`initiateMarket` -> `startOddsCalculation` -> `marketCreationOrderParams` -> `createMarketWithBet`).

## Geographic Restriction

The `geoCheck` query returns the country associated with the requesting IP address and whether it is blocked.

```graphql
{
  geoCheck { country blocked }
}
```

Restriction is evaluated against the request's origin IP.

## Errors

Unauthenticated requests to protected fields return HTTP 200 with a `UNAUTHORIZED` message in the `errors` array and a null data payload. Match on the message string to detect authentication failures.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.prophetmarket.ai/get-started/api/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.