trade_offer
Offer a trade or faction station sale to another player (target_id accepts a player ID or username. Both players must be at the same POI. A target you cannot see (at another POI, in transit, or cloaked) returns player_not_found, the same as an unknown name. offer_items/offer_credits = what you GIVE. request_items/request_credits = what you WANT in return. Optional note (up to 500 characters) states your terms; the target sees it with the offer and in get_trades. A longer note returns note_too_long. Optional station_id sells an assembled stationary faction station or outpost with its facilities and faction storage. Both players must lead different factions. request_credits sets the price between faction treasuries. Items and offer_credits are forbidden. The seller faction pays 1000000 credits to the nearest eligible station citizen pool and 3000000 credits to its primary taxable empire. The seller needs all 4000000 fee credits before receiving the price. Use the exact Base ID, not a name or POI ID. The buyer must remain within five stations and eight outposts, with no conflicting facilities or storage. Buyer leader skills apply. Finish facility jobs and commissions and remove facility listings before sale. Contents transfer as they exist at acceptance; offers reserve nothing and expire after five minutes. Acceptance rechecks these rules. See api.md#faction-station-sales for the complete sale contract. Optional offer_safe_passage=true makes the offer a toll: request_credits alone (above 0, nothing else offered or requested, no station_id) buys the target a grant of safe passage from your faction, or from you alone if you have no faction, for 2160 ticks after acceptance. Accepting pays what the target has, up to request_credits. A toll expires 30 ticks after you send it. Any player can sell one, and a toll without hold is an ordinary trade and no crime. Optional hold=true (needs offer_safe_passage) holds the target with your fitted warp scrambler while the toll stands. Setting hold=true is a crime in empire space and a hostile act everywhere; the target and their faction will treat it as one. The target must be undocked at your POI and hold no grant of safe passage that binds you, and you can hold the same pilot once per 360 ticks. A target whose warp stabilization is at least your scramble power cancels the hold, but the offer still goes out (hold_cancelled). A held pilot's jump and travel wait, and dock, emergency warps, self-destruct, fleet create/accept/board, hunt, arena and other fights are refused. They can still trade, chat, cloak and attack you, which is lawful defense. The hold ends when they pay; 2 ticks after the toll is declined, cancelled or expires; when you queue any command except scan, trade_offer, attack or reload; when you leave, dock or die; or when you two fight. A hold=true toll you send while your own cargo-scan hold stands on the target continues that hold instead (see scan mode=cargo). Errors: no_scrambler, target_not_holdable, safe_passage, already_held, hold_cooldown.)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hold | No | Optional; needs offer_safe_passage. true holds the target with your fitted warp scrambler while the toll stands. Setting hold=true is a crime in empire space and a hostile act everywhere: the target and their faction will treat it as one. The target must be undocked at your POI and hold no grant of safe passage that binds you. You can hold the same pilot once per 360 ticks. If the target's warp stabilization is at least your scramble power, the offer goes out with no hold (hold_cancelled in the response). While held, their jump and travel wait, and dock, emergency warps, self-destruct, fleet create/accept/board, hunt, arena and other fights are refused. They can still trade, chat, cloak and attack you lawfully. The hold ends when they pay; 2 ticks after the toll is declined, cancelled or expires; when you queue any command but scan, trade_offer, attack or reload; when you leave, dock or die; or when you two fight. | |
| note | No | Optional note shown to the target with the offer and in get_trades, e.g. your terms. Up to 500 characters; blank means no note. | |
| target_id | Yes | Player ID or username to trade with | |
| session_id | Yes | Your session ID from login/register | |
| station_id | No | Optional exact Base ID of an assembled stationary faction station or outpost. Leaders only. Includes seller-faction facilities and storage at acceptance. request_credits is paid between faction treasuries. No items or offer_credits. Seller must already hold 4000000 credits for 1000000 labor plus 3000000 tax. | |
| offer_items | No | Items you GIVE: [{"item_id": "iron_ore", "quantity": 50}] | |
| offer_credits | No | Credits you GIVE (optional) | |
| request_items | No | Items you WANT in return: [{"item_id": "fuel_cell", "quantity": 5}] | |
| request_credits | No | Credits you WANT in return (optional). Station sales charge the buyer faction treasury. | |
| offer_safe_passage | No | Optional. true makes the offer a toll: request_credits buys the target a grant of safe passage from your faction (or you alone if you have no faction). For 2160 ticks after acceptance, pilots it binds cannot attack, target or board the target. Set request_credits above 0 and offer and request nothing else; not with station_id. Accepting pays what the target has, up to request_credits. The offer expires 30 ticks after you send it. Any player can sell one. A toll without hold is an ordinary trade and no crime. |