Qortal-External-Auth/docs/trade-api.md

# Trade Helper API

These endpoints are intended for external trading tools that should not hold wallet seeds or foreign-chain private keys directly.

## Managed foreign wallets

The daemon can derive the same deterministic foreign wallets used by Qortal Hub from the unlocked Qortal wallet's address-0 seed. `GET /wallet/foreign?walletId=...` lists supported public metadata, and `POST /wallet/foreign/derive` derives one chain's public metadata.

The response contains the foreign address and extended public key only. The daemon keeps the derivation seed in its encrypted in-memory unlock cache and does not persist or return foreign private keys. The wallet must be unlocked after daemon restart before managed metadata or managed foreign balance/trade requests can be used.

Foreign balance, Q-Trade respond, and foreign-send requests accept `useManagedKey: true`. The daemon derives the chain-specific credential for that request and forwards it to Qortal Core; the credential is never returned to the caller or written to audit metadata. Existing explicit `foreignKey`, `xprv58`, and `entropy58` payloads remain supported for compatibility, but cannot be combined with `useManagedKey`.

The existing generic path remains:

- `POST /tx/sign`
- `POST /node/proxy`
- `POST /qortal/request`

The helpers below provide a narrower, auditable trade surface for Q-Trade and supported foreign coins.

Implemented now:

- `GET /wallet/foreign`
- `POST /wallet/foreign/derive`
- `POST /trade/foreign/balance`
- `POST /trade/foreign/send`
- `POST /trade/qortal/create-sell-offer`
- `POST /trade/qortal/respond-sell-offer`
- `POST /trade/qortal/respond-multiple-sell-offers`
- `POST /trade/qortal/cancel-offer`
- `GET /permissions/status`

## Q-Trade

```txt
POST /trade/qortal/create-sell-offer
POST /trade/qortal/respond-sell-offer
POST /trade/qortal/respond-multiple-sell-offers
POST /trade/qortal/cancel-offer
```

All endpoints require bearer auth and wallet permission. Suggested permission scopes:

```txt
QTRADE_CREATE
QTRADE_RESPOND
QTRADE_CANCEL
```

### Create Sell Offer

```json
{
  "walletId": "wallet-id",
  "foreignBlockchain": "BITCOIN",
  "qortAmount": "100",
  "fundingQortAmount": "100.1",
  "foreignAmount": "0.0003",
  "receivingAddress": "optional foreign receiving address",
  "tradeTimeout": 10080,
  "nodeUrl": "http://127.0.0.1:12391"
}
```

The daemon verifies wallet ownership, requires `QTRADE_CREATE`, fills `creatorPublicKey` from the Qortal wallet, and forwards the request to Qortal Core `/crosschain/tradebot/create`.

### Respond To Sell Offer

```json
{
  "walletId": "wallet-id",
  "atAddress": "AT...",
  "foreignBlockchain": "BITCOIN",
  "useManagedKey": true,
  "xprv58": "foreign-chain-xprv",
  "entropy58": "piratechain-entropy",
  "receivingAddress": "optional QORT receiving address; defaults to wallet address",
  "nodeUrl": "http://127.0.0.1:12391"
}
```

The daemon verifies wallet ownership, requires `QTRADE_RESPOND`, and forwards to Qortal Core `/crosschain/tradebot/respond`. Use `useManagedKey: true` when the selected Qortal wallet is unlocked; otherwise provide one of `foreignKey`, `xprv58`, or `entropy58` for compatibility.

### Respond To Multiple Sell Offers

```json
{
  "walletId": "wallet-id",
  "atAddresses": ["AT...", "AT..."],
  "foreignBlockchain": "LITECOIN",
  "useManagedKey": true,
  "receivingAddress": "optional QORT receiving address",
  "nodeUrl": "http://127.0.0.1:12391"
}
```

The daemon verifies wallet ownership, requires `QTRADE_RESPOND`, derives one foreign credential, and forwards the address array to Qortal Core `/crosschain/tradebot/respondmultiple`. This is the preferred path when several same-chain Q-Trade buys should be issued before the foreign-wallet balance/change-address state is refreshed. Piratechain remains on the single-offer endpoint because Qortal Hub uses the single-response flow for ARRR.

### Cancel Offer

```json
{
  "walletId": "wallet-id",
  "atAddress": "AT...",
  "process": false,
  "nodeUrl": "http://127.0.0.1:12391"
}
```

The daemon builds the cancel transaction via Qortal Core `/crosschain/tradeoffer`, signs it with the Qortal wallet, requires `QTRADE_CANCEL`, and processes it unless `process=false`.

## Foreign Coins

```txt
POST /trade/foreign/balance
POST /trade/foreign/send
```

Suggested permission scopes:

```txt
FOREIGN_BALANCE
FOREIGN_SEND
```

Supported `foreignBlockchain` values should match Qortal Core naming:

```txt
BITCOIN
LITECOIN
DOGECOIN
DIGIBYTE
RAVENCOIN
PIRATECHAIN
```

### Balance

```json
{
  "walletId": "wallet-id",
  "foreignBlockchain": "LITECOIN",
  "useManagedKey": true,
  "nodeUrl": "http://127.0.0.1:12391"
}
```

The balance endpoint does not mutate wallet state. It requires bearer auth, verifies that the `walletId` belongs to the authenticated app, and reads the matching Qortal Core cross-chain wallet balance endpoint through the daemon's configured node URL. With `useManagedKey: true`, Qortal Core receives the route-specific derived credential without the caller seeing it. Explicit `xprv58` (or a public `xpub` where supported) remains available for BTC/LTC/DOGE/DGB/RVN, and `entropy58` remains available for ARRR; explicit credentials are forwarded only for the request and are not stored or audited.

### Send

```json
{
  "walletId": "wallet-id",
  "foreignBlockchain": "LITECOIN",
  "destinationAddress": "address",
  "amount": "0.1",
  "useManagedKey": true,
  "feePerByte": "optional",
  "nodeUrl": "http://127.0.0.1:12391"
}
```

`POST /trade/foreign/send` requires `FOREIGN_SEND` and forwards to the matching Qortal Core `/crosschain/<coin>/send` endpoint. For BTC/LTC/DGB/RVN/DOGE, use `useManagedKey: true` or provide `xprv58`/`foreignKey`. For ARRR, use `useManagedKey: true` or provide `entropy58`/`foreignKey`; `memo` is supported.

## Safety Notes

- Every state-changing helper should write an audit log entry with app id, wallet id, route, amount, and node URL.
- Withdraw/send helpers should never be enabled by broad `SIGN_TRANSACTION` permission alone.
- Prefer chain-specific permission scopes for foreign sends.
- Qortal wallet backup import/unlock covers the Qortal signing key and, while unlocked, supplies the deterministic address-0 seed used by the managed foreign-key path. Foreign private material remains daemon-internal and is not added to the Qortal backup, bot storage, API response, or audit log.