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

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:

QTRADE_CREATE
QTRADE_RESPOND
QTRADE_CANCEL

Create Sell Offer

{
  "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

{
  "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

{
  "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

{
  "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

POST /trade/foreign/balance
POST /trade/foreign/send

Suggested permission scopes:

FOREIGN_BALANCE
FOREIGN_SEND

Supported foreignBlockchain values should match Qortal Core naming:

BITCOIN
LITECOIN
DOGECOIN
DIGIBYTE
RAVENCOIN
PIRATECHAIN

Balance

{
  "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

{
  "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.