📄 Public API Documentation

API Reference#

The AutoPlus public API uses HTTPS and JSON. It provides public AutoPlus statistics and user-authenticated endpoints for opening and automating escrow trades.

Base URL#

https://api.autoplus.gg/v1

Version v1 is currently the only available API version.

Authentication#

Every trade endpoint requires an API token associated with one Discord user. Send it using the bearer authentication scheme:

Authorization: Bearer YOUR_API_TOKEN

Open a support ticket in the AutoPlus Discord server to request an API token. Keep it private and use it only from a trusted server.

The /servers, /stats, and /transactions endpoints do not require authentication.

Request format#

Requests with a body must include Content-Type: application/json.

Discord user IDs, guild IDs, and trade IDs are JSON strings. Timestamps are integer Unix timestamps in seconds. Optional response fields are omitted when they have no value.

Idempotency#

The following endpoints require an Idempotency-Key header:

POST /guilds/{guildId}/trades
POST /trades/{id}/confirm-action
POST /trades/{id}/confirm-claim

The key must contain 8 to 128 characters. Use a unique random value for each new operation. If a request times out, retry the identical request with the same key. Reusing a key with different request data returns 409 Conflict.

Crypto type#

The Crypto type identifies both the asset and, for tokens, its network:

"ltc" | "sol" | "eth" | "bnb" | "btc" | "pol" | "sol_usdt" | "sol_usdc" | "eth_usdt" | "eth_usdc" | "bnb_usdt" | "bnb_usdc" | "pol_usdt" | "pol_usdc" | "pol_usdce"

Availability also depends on the networks currently enabled by AutoPlus.

Trade automation rules#

The authenticated user must be the sender or receiver of every trade they access.
Route parameter id is the Discord trade thread ID returned by trade creation, not the incremental tradeId.
Identification and terms confirmations must repeat the exact values from the latest trade response.
Only the sender can release funds. Only the receiver can return funds.
Release, return, and claim operations use short-lived confirmation challenges.
A successful claim confirmation returns 202 Accepted; poll trade events for the final result.
The API can provide a reduction return address when a trade is already in waitingReduceAmountAddress, but it cannot initiate a reduction.

Public Endpoints#

GET

/servers

Get the list of Discord servers AutoPlus is in.

Response Structure

Each object in the returned array has this structure:

Field	Type	Description
`id`	`string`	Discord server ID.
`name`	`string`	Discord server name.
`icon`	`string`	Server icon URL.

GET

/stats

Get global AutoPlus trade statistics.

Response Structure

Field	Type	Description
`trades`	`number`	Total completed and canceled trades.
`volume`	`number`	Total completed and canceled volume in USD.
`canceledTrades`	`number`	Total canceled trades.
`canceledVolume`	`number`	Total canceled volume in USD.
`trades24h`	`number`	Trades recorded during the last 24 hours.
`volume24h`	`number`	Volume recorded during the last 24 hours in USD.

GET

/transactions

Get the 10 most recent public AutoPlus transactions.

Response Structure

Each object in the returned array has this structure:

Field	Type	Description
`crypto`	`Crypto`	Crypto used by the trade.
`amount`	`number`	Transaction amount in the selected crypto.
`amountUsd`	`number`	Transaction amount valued in USD.
`txid`	`string`	Incoming escrow transaction ID.
`txid2`	`string`	Settlement transaction ID.
`receivedAt`	`number`	Timestamp when escrow received the funds.
`closedAt`	`number`	Timestamp when the trade closed.

Authenticated Endpoints#

All endpoints in this section require bearer authentication.

POST

/guilds/{guildId}/trades

Create a trade in an API-enabled Discord server.

Requires bearer authentication and an Idempotency-Key header.

Request Structure

Field	Type	Description
`crypto`	`Crypto`	Crypto and network used by the trade.
`sender`	`string`	Discord user ID of the participant funding escrow.
`receiver`	`string`	Discord user ID of the participant receiving released funds.

The authenticated user must be either sender or receiver. Both participants must be different, non-bot members of the guild.

Response Structure — 201 Created

Field	Type	Description
`id`	`string`	Discord thread ID used as {id} in every other trade endpoint.
`tradeId`	`number`	Human-readable incremental trade number.

GET

/trades/{id}

Get the current public representation of a trade.

Requires bearer authentication. The caller must be a participant.

Response — 200 OK

Returns a Trade. The escrow deposit address is exposed only to the sender.

GET

/trades/{id}/events

Poll durable trade events using a client-managed offset.

Requires bearer authentication. Maximum two concurrent polls per token and trade.

Query Parameters

Field	Type	Description
`offset?`	`number`	Last processed event ID. Omit to receive a current snapshot.
`timeout?`	`number`	Long-poll timeout in seconds. Defaults to 55 and is capped at 60.

Response Structure — 200 OK

Field	Type	Description
`events`	`TradeEvent[]`	Events after the supplied offset, in chronological order.
`nextOffset`	`number`	Offset to send with the next poll.

An empty events array means the poll timed out without a new event. Repeat the same offset. If retained history expired, the API returns a current trade.snapshot.

PUT

/trades/{id}/identification

Select the authenticated user's role after identification was reset.

Valid only while the trade is waiting for identification.

Request Structure

Field	Type	Description
`role`	`"sender" \| "receiver"`	Role assigned to the authenticated user.
`revision`	`number`	Current identificationRevision from the trade.

Response — 200 OK

Returns the updated Trade.

POST

/trades/{id}/identification/confirm

Confirm the exact current sender and receiver assignment.

Request Structure

Field	Type	Description
`sender`	`string`	Exact current sender Discord user ID.
`receiver`	`string`	Exact current receiver Discord user ID.
`revision`	`number`	Current identificationRevision from the trade.

Response — 200 OK

Returns the updated Trade. After both participants confirm the same revision, the trade moves to waitingTermsAcceptance.

POST

/trades/{id}/identification/reset

Clear both role assignments and their confirmations.

Request Structure

Field	Type	Description
`sender`	`null`	Must be null.
`receiver`	`null`	Must be null.
`revision`	`number`	Current identificationRevision from the trade.

Response — 200 OK

Returns the updated Trade.

PUT

/trades/{id}/terms

Set, replace, or clear the authenticated user's terms.

Valid only while the trade is waiting for terms acceptance.

Request Structure

Field	Type	Description
`text`	`string \| null`	Terms text, up to 896 characters. Use null to clear it.
`version`	`string`	Current terms.version from the trade.

Each update creates a new terms version and clears existing confirmations.

Response — 200 OK

Returns the updated Trade.

POST

/trades/{id}/terms/confirm

Confirm the complete current terms exactly as returned by the API.

Request Structure

Field	Type	Description
`sender`	`string \| null`	Exact current sender terms, or null when absent.
`receiver`	`string \| null`	Exact current receiver terms, or null when absent.
`version`	`string`	Exact current terms version.

Response — 200 OK

Returns the updated Trade. After both participants confirm, the trade moves to waitingReceive. The sender's response then includes the escrow deposit address.

POST

/trades/{id}/action

Request a short-lived confirmation challenge for releasing or returning funds.

Valid at waitingAction. Sender may release; receiver may return.

Request Structure

Field	Type	Description
`action`	`"release" \| "return"`	Requested fund action.

Response Structure — 201 Created

Field	Type	Description
`action`	`"release" \| "return"`	Action bound to the challenge.
`recipient`	`string`	Discord user ID that will receive the funds.
`confirmationCode`	`string`	Secret confirmation code valid for 60 seconds.
`expiresAt`	`number`	Challenge expiration timestamp.

POST

/trades/{id}/confirm-action

Confirm a release or return challenge.

Requires an Idempotency-Key header.

Request Structure

Field	Type	Description
`action`	`"release" \| "return"`	Exact action returned by the challenge.
`recipient`	`string`	Exact recipient returned by the challenge.
`confirmationCode`	`string`	Confirmation code returned by the challenge.

Response — 200 OK

Returns the updated Trade. Release moves the trade to waitingAddress; return moves it to waitingReturnAddress.

POST

/trades/{id}/claim-funds

Request a confirmation challenge for a payout, return, or reduction-return address.

Receiver claims at waitingAddress. Sender claims at waitingReturnAddress or waitingReduceAmountAddress.

Request Structure

Field	Type	Description
`address`	`string`	Destination address valid for the trade crypto.
`crypto`	`Crypto`	Exact crypto value from the trade.

Response Structure — 201 Created

Field	Type	Description
`address`	`string`	Address bound to the challenge.
`crypto`	`Crypto`	Crypto bound to the challenge.
`confirmationCode`	`string`	Secret confirmation code valid for 60 seconds.
`expiresAt`	`number`	Challenge expiration timestamp.
`btcFeeOptions?`	`BtcFeeOption[]`	Available fee choices for BTC claims only.

POST

/trades/{id}/confirm-claim

Confirm the destination and begin the fund transfer.

Requires an Idempotency-Key header.

Request Structure

Field	Type	Description
`address`	`string`	Exact original address returned by the challenge.
`crypto`	`Crypto`	Exact crypto returned by the challenge.
`confirmationCode`	`string`	Confirmation code returned by the challenge.
`btcFee?`	`BtcFee`	One unchanged BTC fee option. Omit for non-BTC trades.

Response Structure — 202 Accepted

Field	Type	Description
`executionId`	`string`	Fund execution identifier.
`status`	`"pending"`	The transfer was accepted for asynchronous processing.

Continue polling trade events. trade.fund.execution.updated reports execution progress and trade.closed reports the final release or return.

Response Structures#

Trade#

Field	Type	Description
`id`	`string`	Discord trade thread ID used in API routes.
`tradeId`	`number`	Human-readable incremental trade number.
`revision`	`number`	Current public trade revision.
`openedAt`	`number`	Timestamp when the trade opened.
`crypto`	`Crypto`	Crypto and network selected for the trade.
`status`	`TradeStatus`	Current trade lifecycle status.
`sender?`	`string`	Sender Discord user ID. Omitted while identification is reset.
`receiver?`	`string`	Receiver Discord user ID. Omitted while identification is reset.
`identificationRevision`	`number`	Revision used for identification updates and confirmations.
`identificationConfirmedBy`	`string[]`	Participant IDs that confirmed the current identification.
`terms?`	`TradeTerms`	Current terms and confirmation state.
`address?`	`string`	Escrow deposit address. Exposed only to the sender.
`fees?`	`number`	Network fees in the selected crypto.
`feesUsd?`	`number`	Estimated network fees in USD.
`amount?`	`number`	Amount received by escrow in the selected crypto.
`amountUsd?`	`number`	Received amount valued in USD.
`receivedAt?`	`number`	Timestamp when the deposit was received.
`txid?`	`string`	Incoming deposit transaction ID.
`settlementTxid?`	`string`	Final payout or return transaction ID.
`fundControlsLocked?`	`boolean`	True when fund actions are temporarily locked.

TradeStatus#

"waitingIdentification" | "waitingTermsAcceptance" | "waitingReceive" | "waitingConfirmations" | "waitingAction" | "waitingReduceAmountAddress" | "waitingReturnAddress" | "waitingAddress" | "completed"

TradeTerms#

Field	Type	Description
`version`	`string`	Opaque version required for terms updates and confirmations.
`sender`	`TradeTermsSide`	Sender terms and confirmation state.
`receiver`	`TradeTermsSide`	Receiver terms and confirmation state.

Each TradeTermsSide contains:

Field	Type	Description
`text?`	`string`	Terms text. Omitted when no terms were set.
`confirmed`	`boolean`	Whether this participant confirmed the current version.
`confirmedAt?`	`number`	Confirmation timestamp.

TradeEvent#

Field	Type	Description
`id`	`number`	Monotonically increasing event ID within the trade.
`type`	`TradeEventType`	Event category.
`occurredAt`	`number`	Timestamp when the event occurred.
`changes`	`TradeEventChanges`	Changed public fields and optional status or outcome information.
`trade`	`Trade`	Complete API trade snapshot at this event.

"trade.snapshot" | "trade.created" | "trade.identification.updated" | "trade.terms.updated" | "trade.status.changed" | "trade.fund.execution.updated" | "trade.support.updated" | "trade.closed"

Events are retained for at least one hour. A closed trade may no longer be returned by GET /trades/{id}, but its retained event stream remains available to its participants.

BTC fee types#

Field	Type	Description
`priority`	`"high" \| "medium" \| "none"`	Fee priority returned by AutoPlus.
`satPerVbyte`	`number`	Fee rate that must be returned unchanged.
`estimatedCostUsd`	`number`	Estimated transfer cost. Present in BtcFeeOption responses only.

Errors#

API errors use the HTTP status code as the primary result and return:

Field	Type	Description
`code`	`string`	Stable machine-readable error code.
`message`	`string`	Human-readable error description.
`requestId`	`string`	Request identifier to provide when contacting support.
`details?`	`object`	Optional safe machine-readable context.

Common status codes:

Field	Type	Description
`400`	`Bad Request`	Malformed JSON, missing field, or invalid field type.
`401`	`Unauthorized`	Bearer token is missing, invalid, expired, or revoked.
`403`	`Forbidden`	The authenticated user or guild cannot perform the operation.
`404`	`Not Found`	Trade does not exist or the caller is not a participant.
`409`	`Conflict`	Wrong state, stale revision, confirmation mismatch, or idempotency conflict.
`410`	`Gone`	Confirmation challenge expired. Request a new challenge.
`422`	`Unprocessable Content`	Invalid address, crypto, or semantic request data.
`429`	`Too Many Requests`	A rate or concurrent polling limit was exceeded.
`500`	`Internal Server Error`	Unexpected internal failure.
`503`	`Service Unavailable`	A required AutoPlus dependency is unavailable.

On stale_revision or confirmation_mismatch, fetch the trade again and compare the new values before asking the user to confirm them. Never automatically confirm changed roles, terms, recipients, crypto, or addresses.

« Points System

Referral System »

View MarkdownEdit on GitHub