# Introduction

The Restake Partner API lets your backend read staking pool and tokenized
equity and commodity data, manage the users you onboard, build and submit
staking transactions, stock trades and cross-chain bridges on their behalf, and
read back the portfolio those transactions produce.

It is a **server-to-server** API. You authenticate as an organisation with a
client ID and secret, never as an end user, and every call is made from your
own backend - the credentials must never reach a browser or a mobile app.

## Base URLs

| Environment | Base URL |
| --- | --- |
| Production | `https://s2s.restake.gg` |
| Staging | `https://stg-s2s.restake.gg` |

The two hosts are the same API against different data and different money.
Build against staging, and switch the host - nothing else - when you go live.
Every example in these guides uses the staging host for that reason.

Every partner endpoint lives under `/api/v1/s2s/`. The machine-readable
description of this reference is served from the API itself, per host:

```
https://s2s.restake.gg/api/v1/s2s/openapi.json
https://stg-s2s.restake.gg/api/v1/s2s/openapi.json
```

Point a client generator or Postman at that URL - it is generated from the
running service, so it never describes a route the API does not have.

## Response shapes

Two shapes, and which one you get depends on the endpoint:

| Endpoint | Shape |
| --- | --- |
| `POST /api/v1/s2s/auth/token` | The RFC 6749 token response - `access_token`, `token_type`, `expires_in`, `scope` - so stock OAuth clients work unmodified |
| Everything else | `{ "data": … }`, with list endpoints adding pagination alongside it |

Errors are the standard HTTP statuses. The token endpoint answers with the
OAuth error shape (`{ "error": "invalid_client", "error_description": … }`);
every other endpoint uses the API's error envelope. See
[Errors](/errors) for how to tell the failure modes apart.

## Your users belong to you

Every account you create through this API is tagged with your partner ID, and
that tag is the boundary of what you can see. A user ID that belongs to another
partner - or to somebody who signed up through the Restake app directly -
answers `404`, not `403`: the API will not confirm that an account it will not
show you exists at all.

There is no endpoint that reaches across that boundary, including the
transaction endpoints, which resolve the user you name and refuse anything you
do not own.

## Environments

Credentials are issued as either `live` or `sandbox`, and the environment is
carried inside the access token. A credential belongs to the host it was issued
for: a staging credential does not authenticate against `s2s.restake.gg`, and a
production one is not accepted by staging. Check which one you are holding with
`GET /api/v1/s2s/me` - it is the first call worth making, because it proves your
credentials, your token and your network path all work before any business logic
is involved.

## Getting started

Read [How it works](/how-it-works) first for the path every transaction takes,
from your backend through the user's wallet to the chain.

1. [Authenticate](/authentication) - exchange your client credentials for an
   access token.
2. [Create a user](/users) and link their wallet address.
3. [Build and submit a stake](/staking) - or [a stock trade](/stocks), or
   [a bridge](/bridge) - for that user.
4. [Read their portfolio](/portfolio) - balances, transfers and open positions.