API and MCP

The Sway API is a JSON REST API. The brand console, the integrator console, the operator page and the @sway/mcp package all use it, and you can call it directly.

The OpenAPI document is generated from the same schemas the server validates against, and it marks each operation's role with x-sway-auth. These addresses serve the API's documents and parameters; the endpoint tables below list its operations.

Conventions

• Request and response bodies are JSON. A request body may be at most 16,384 bytes, and every object rejects fields it does not declare.
• Money is a decimal string of USDC base units: "15000000" is 15 USDC. It is never a floating-point number.
• Public keys and wallet addresses are base58. Signatures, ciphertext and 128-byte messages are standard padded base64. Hashes are 64 lowercase hex characters.
• IDs are opaque strings of letters, digits, _ and -.
• Lists take cursor and limit (1 to 100) and return { items, nextCursor, sync }, where sync.status is ready, indexing or failed.
• Browsers can call the API only from the origins the deployment allows. Server-side callers send no Origin header.
• Every response carries Cache-Control: no-store and X-Sway-Mode.

Response envelope

A success wraps the result in data:

{
  "data": { "id": "…", "status": "confirmed" },
  "meta": { "mode": "live", "scenario": "default", "requestId": "…" }
}

A failure carries error instead, with the HTTP status set to match:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request does not match the contract.",
    "retryable": false,
    "details": { "fields": [{ "field": "amount", "message": "This field has an invalid format." }] }
  },
  "meta": { "mode": "live", "scenario": "default", "requestId": "…" }
}

details may also hold retryAfterSeconds, requiredConfiguration or resourceId. A 429 response also sets Retry-After.

Authentication

Each operation belongs to one role. The role decides how a request proves who sent it.

One-use challenges

Sign-in, registrations, claims and disputes use challenges. Request one with POST /v1/auth/challenges:

{ "purpose": "claim", "publicKey": "<signer>", "resourceIds": ["<claimable id>"], "requestHash": "<sha256 hex>" }

The response holds id, purpose, publicKey, expiresAt and the exact message to sign:

Sway authorization v1
Audience: <audience origin>
Purpose: <purpose>
Public-Key: <signer public key>
Nonce: <43 random base64url characters>
Issued-At: <ISO 8601 time>
Expires-At: <ISO 8601 time>
Request-SHA256: <requestHash>
Resources-SHA256: <SHA-256 of the canonical JSON of the sorted resource IDs>

Sign the UTF-8 bytes of message with Ed25519 and send the proof as the body field authorization:

{ "challengeId": "<id>", "publicKey": "<signer>", "signatureBase64": "<64-byte signature, base64>" }

A proof works for one operation, one payload and one set of resources, once, until expiresAt. requestHash is the SHA-256 of the canonical JSON of the request body without its authorization field, except for sign-in.

Merchant session

1. Request a merchant_session challenge for the wallet and sign its message with the wallet.
2. Send POST /v1/auth/merchant/session with an Idempotency-Key and { "authorization": <proof> }.
3. The response carries accessToken, a 43-character token, and expiresAt. Send it as Authorization: Bearer <accessToken>.

GET /v1/auth/merchant/session reads the session and DELETE /v1/auth/merchant/session ends it. The Config admin wallet signs in the same way, without registering a merchant, and uses its session to submit the activation transactions it signs.

Signed requests: SwayAgent, SwayIntegrator, SwayAdmin and SwayOracle

Agents, integrators, the operator and the affiliate oracle sign each HTTP request. The header is:

Authorization: <Scheme> <keyId>:<timestamp>:<nonce>:<signatureBase64>

The signed message is these nine lines, joined with \n:

Sway signed request v1
Audience: <audience>
Principal: <Scheme>
Key: <keyId>
Timestamp: <timestamp>
Nonce: <nonce>
Method: <HTTP method in upper case>
Path: <path and query string exactly as sent>
Body-SHA256: <SHA-256 hex of the canonical JSON body>

Audience is the value GET /v1/encryption returns as authorizationAudience. For a request without a body, such as a GET, the body hash is the hash of {}. The agent key signs SwayAgent requests, the integrator authority signs SwayIntegrator requests, and the operator's and oracle's allowed keys sign SwayAdmin and SwayOracle requests. A browser wallet signs the message's UTF-8 bytes as a message signature. Sign a fresh request, with a new nonce, for every attempt, including retries.

Canonical JSON

Hashes cover canonical JSON. Object keys are sorted by UTF-16 code unit, with no whitespace anywhere. Strings, finite numbers, booleans and null are written as standard JSON, and arrays keep their order. {"b":1,"a":[true,null]} becomes {"a":[true,null],"b":1}.

Idempotency keys

Every mutation marked in the tables below requires an Idempotency-Key header of 1 to 128 characters. The key is scoped to the caller and the operation. Repeating a request with the same key returns the original result. Reusing the key for a different request returns 409 IDEMPOTENCY_CONFLICT, and leaving it out returns 400 IDEMPOTENCY_REQUIRED. Use a fresh key for each new action and the same key for each retry of it.

Wallet transactions

Merchant mutations that change chain state, and the operator's merchant activation, suspension, bond release and shopper-side dispute resolution, return a prepared transaction: { id, kind, resourceId, requiredSigner, status, unsignedTransactionBase64, signature, expiresAt, failure, simulationOnly }. Legacy and v0 transactions are both accepted.

1. Sign unsignedTransactionBase64 with the wallet named in requiredSigner. The prepared instructions, their order, the blockhash, the fee payer and the signer set stay unchanged. The wallet may add compute-budget instructions before them and a Lighthouse guard after them, and nothing else; no account may become newly writable.
2. Send it one of two ways, with the wallet session of the signer:
   • Through Sway: POST /v1/transactions/{id}/submit with { "signedTransactionBase64": "…" }. Sway simulates the transaction first and answers TRANSACTION_SIMULATION_FAILED if it would not execute; prepare a fresh one after correcting balances or state.
   • From the wallet: when the wallet broadcasts it itself, as with solana:signAndSendTransaction, report it with POST /v1/transactions/{id}/report and { "signature": "<base58 transaction signature>" }. Sway fetches the transaction, applies the same checks to its instructions and signers, and tracks it without sending it again. Retry with the same signature while the RPC has not yet indexed it.
3. Poll GET /v1/transactions/{id} until status is confirmed, failed or expired.

Endpoints

The "Key" column marks operations that require Idempotency-Key.

Public

Merchant (brand session)

The three transaction routes also take the Config admin wallet's session, for the activation transactions it signs.

Receipt signer

A receipt body carries merchantId, signerPublicKey, payloadBase64 (the 128 signed receipt bytes), signatureBase64 and proposedRebateUsdc, the merchant's proposal of the rebate in base units. Arcium's verification checks that the proposal equals the sealed winning offer before the program records or escrows anything. The response is the conversion, at verification_pending; poll GET /v1/conversions/{id} until it is locked. A rejected proposal moves nothing: send the same signed receipt again with the corrected proposal and a new Idempotency-Key.

Integrator (SwayIntegrator)

Agent (SwayAgent)

Claim key

A claim body carries claimPublicKey, one ID in claimableIds, destination and the challenge proof. It also carries claimMessageBase64, a 128-byte SWAYCLM1 message that binds the program, the conversion account, the destination wallet, an expiry and a nonce, and claimSignatureBase64, the claim key's signature over it. The program checks that signature before it pays.

Operator (SwayAdmin)

The Sway operator signs each of these with a SwayAdmin request from a key the deployment allows. The operator page at https://swayoffers.com/admin calls them with the Config admin wallet.

Activation, suspension and bond release are prepared only for the program's Config admin and only once the merchant's registration is final on chain. Each returns a prepared transaction: the admin wallet signs it and sends it with POST /v1/transactions/{id}/submit or /report under its own wallet session. The program activates the merchant when its bond holds at least minimum_bond. A bond release takes no amount or destination: Sway computes the whole bond balance and pays it to the merchant wallet's own USDC account, and answers BOND_LOCKED while the program would refuse the release. Approval changes the integrator's status from pending to active at once, and its authority can then register agent keys.

A resolve body carries outcome, one of user, merchant or reject; bondDebit, in USDC base units, positive and at most 50 USDC for user and "0" otherwise; and resolutionHash, 64 lowercase hex characters. The operator page sets resolutionHash to the SHA-256 of the operator's resolution note. A user outcome leaves the dispute under_review and returns transaction, a prepared slash_bond that pays the compensation address from the bond. The admin wallet signs and sends it like the transactions above, and the dispute becomes resolved_user once that debit is final on chain. merchant and reject are recorded by the signed request alone.

Affiliate oracle (SwayOracle)

These routes answer CONFIGURATION_REQUIRED until the deployment connects an affiliate network.

MCP tools

GET https://api.swayoffers.com/v1/mcp/tools returns the five tools of @sway/mcp, each as { name, description, inputSchema, outputSchema, operationId }, with followUpOperationId where the tool polls. These are the schemas the package validates against. The package performs the encryption, key storage and signing, then calls the REST operations listed here.

Installation, inputs and outputs are in For agent developers.