Authentication

Public reads need nothing. Everything else is authenticated by an ed25519 signature the caller produces, over the exact request they are making.

The two values

How a user generates one

1. 1Open Swapmos in a browser and connect the wallet the account belongs to.
2. 2Open the futures terminal and press Enable trading.
3. 3The browser generates an ed25519 key pair. The wallet signs a typed message binding the public half to the account, and the app posts that to /api/prep/trading-key. The secret half stays in the browser.
4. 4Copy the account id and the 32 byte secret into your own client's configuration. That pair is everything a third party needs.

What the key can and cannot do

• It is scoped to reading and trading. It can place, cancel and close, and read the account it belongs to.
• It is not a wallet private key and not a seed phrase. Nothing in this API has a field for one.
• It cannot withdraw. A withdrawal is signed by the wallet itself, upstream, in addition to this key, so a trading key alone moves nothing off the exchange. The withdrawal paths are reachable through the relay precisely because the wallet signature is what actually authorises them.
• It expires. The expiration is chosen when the key is bound and comes back from POST /api/prep/trading-key. Past it, every signed call fails.
• It can be revoked in the app without touching the wallet, and balances belong to the account rather than to the key.

Signing a private request

The signature covers exactly this string, and nothing else:

timestamp + METHOD + path + body

No host, no origin and no headers are covered, which is why the signature survives being relayed. You sign for the upstream path; this server forwards your signature unchanged and never holds a key of yours.

1. 1Take a millisecond timestamp, Date.now().
2. 2Serialise the body once, to a string. That exact string is what you sign and what you send.
3. 3Concatenate timestamp, the uppercased method, the path including its query string, and the body string. Omit the body entirely when there is none.
4. 4Sign those bytes with the 32 byte ed25519 secret.
5. 5Encode the signature as base64url with no padding.
6. 6POST the envelope below to /api/prep/relay.

POST/api/prep/relay

The one door for every private call, read or write. It forwards a request you already authorised; it cannot produce a signature, so it cannot act for anyone.

curl -X POST https://swapmos.com/api/prep/relay \
  -H 'content-type: application/json' \
  -d '{
    "method": "GET",
    "path": "/v1/positions",
    "auth": {
      "accountId": "0x<64 hex characters>",
      "key": "ed25519:<base58 public key>",
      "signature": "<base64url signature>",
      "timestamp": "1717171717171"
    }
  }'

The response is the upstream payload for that path, scrubbed, at the top level. This endpoint does not reshape it, so its fields are the upstream's own names.

What the relay will forward

An allowlist, anchored at both ends and matched against the path including its query string. Anything outside it is refused with forbidden before it leaves this server, so this is a relay for the calls this product makes rather than an open proxy.

This endpoint is rate limited twice: once against your address, and once against the account id in the envelope, so one busy account behind a shared exit node cannot throttle everybody else on it.

The agent endpoint takes headers instead

POST /mcp, the Model Context Protocol endpoint, accepts the same two credentials as headers and does the signing for you. It is the only place in this product that reads them.

Creating an account

Three endpoints, in this order. All three are public, because each one carries a wallet signature that is what actually authorises it.

GET/api/prep/registration-nonce

No parameters. The nonce is bound into the message the wallet signs, which is what stops a captured signature creating the account twice.

{ "nonce": "1234567890" }

POST/api/prep/register

{ "accountId": "0x<64 hex characters>", "created": true }

An address that already has an account is not an error. It comes back as { "created": false } with no account id, because registering twice is the second person to press the button rather than a failure.

POST/api/prep/trading-key

{ "bound": true, "expiration": 1748000000000 }

All three are on the write policy, which is ten requests a minute with a burst of five. That is deliberate: account creation is not a polling loop.