Reference

This page is the wire-format reference for the execution gateway. The SDK abstracts everything here; read it when you’re building tooling that doesn’t use the SDK or you need to understand a payload on the wire.

Endpoints

All paths are relative to the gateway’s gatewayUrl (e.g. https://gateway.flashnet.xyz).

Method	Path	Auth	Purpose
`POST`	`/api/v1/auth/challenge`	none	Request a challenge string for the given public key.
`POST`	`/api/v1/auth/verify`	none	Submit `{ publicKey, signature }`. Returns `{ accessToken }`.
`GET`	`/api/v1/network/info`	none	Runtime discovery (deposit address, chain id, paused flag).
`GET`	`/api/v1/health`	none	Liveness check.
`POST`	`/api/v1/execute`	bearer	Submit a signed intent.
`GET`	`/api/v1/intents/{submissionId}`	bearer	Look up intent status by submission id.

The bearer token returned from /auth/verify goes in Authorization: Bearer <token> for /execute and any other authenticated endpoint.

Network info

GET /api/v1/network/info

{
  "spark": {
    "depositAddress": "sprt1...",
    "network": "REGTEST"
  },
  "execution": {
    "contractAddress": "0x...",
    "chainId": 21022
  },
  "paused": false,
  "minDepositSats": 1000
}

Cached client-side for 60 seconds. Pass ?forceRefresh=1 (or getNetworkInfo({ forceRefresh: true }) in the SDK) to bypass after a suspected gateway re-key.

Submit intent

The body is flat camelCase. Either recipient (deposit-only) or evmTransaction (deposit-and-execute) is set, never both. The signer is identified by the bearer token; there’s no publicKey field on the body.

POST /api/v1/execute
Authorization: Bearer <token>

{
  "chainId": 21022,
  "deposits": [
    {
      "sparkTransferId": "a1b2c3d4e5f60718a1b2c3d4e5f60718",
      "asset": { "type": "btc" },
      "amount": 100000
    }
  ],
  "evmTransaction": "0xf86c...",
  "signature": "<DER-encoded secp256k1 ECDSA hex>",
  "nonce": "d4e5f607-1234-5678-9abc-def012345678",
  "expiresAt": 1735689600000
}

Field	Required	Notes
`chainId`	yes	Execution chain id. Must match `getNetworkInfo().execution.chainId`.
`deposits`	yes (may be `[]`)	Spark transfers funding the intent. Each entry has `sparkTransferId` (hex), `asset` (`{ "type": "btc" }` or `{ "type": "token", "tokenId": "<32-byte hex>" }`), and `amount` (u64 in base units).
`recipient`	one of these two	EVM address (`0x` + 20 bytes) credited for deposit-only intents. Mutually exclusive with `evmTransaction`.
`evmTransaction`	one of these two	Hex-encoded RLP-serialized signed EIP-1559 transaction. The deposit recipient is the recovered signer. Mutually exclusive with `recipient`.
`signature`	yes	Hex-encoded secp256k1 ECDSA signature over the canonical intent message.
`nonce`	yes	Unique per signer. Replay-protected.
`expiresAt`	yes	Absolute unix-milliseconds. Past or >24h-future timestamps are rejected at admission.

The response:

{
  "submissionId": "7189726361600000001",
  "intentId": "0x6f9d...",
  "status": "accepted"
}

Look up intent status

GET /api/v1/intents/{submissionId}
Authorization: Bearer <token>

{
  "submissionId": "7189726361600000001",
  "intentId": "0x6f9d...",
  "status": "included_pending_finality",
  "statusMessage": null,
  "executionTxHash": "0x...",
  "createdAt": "2026-05-04T12:00:00Z",
  "updatedAt": "2026-05-04T12:00:02Z"
}

executionTxHash is null before inclusion. statusMessage is non-null on rejection (revert reason, oracle failure, admission failure).

Canonical intent message

The signed preimage. Order and field names are stable; the signer hashes JSON serialization in this exact shape.

interface CanonicalIntentMessage {
  chainId: number;
  transfers: CanonicalTransferEntry[];
  action: CanonicalIntentAction;
  nonce: string;
  expiresAt: number;
}

interface CanonicalTransferEntry {
  transferId: string;       // 64-char hex (32 bytes), Bitcoin or token
  amountSats: number;
  assetType: "NativeSats" | "SparkToken";
  tokenId?: string;         // required when assetType is "SparkToken"
}

type CanonicalIntentAction =
  | { type: "deposit"; recipient: string }       // 0x-prefixed EVM address
  | { type: "execute"; signedTxHash: string };   // keccak256 of signedTx

Serialization is camelCase JSON. The signer SHA-256 hashes the UTF-8 bytes of this JSON, then signs with secp256k1 ECDSA (DER encoding). The validator side reproduces the preimage and verifies against the supplied public key. The canonical message uses different field names than the wire format: transfers (not deposits) and transferId (not sparkTransferId). If you’re constructing the signed preimage by hand, use the names above. If you’re using the SDK, this is hidden from you.

Status enum

accepted -> oracle_pending? -> included_pending_finality -> finalized
                                                         \-> rejected
                                                         \-> expired

Wire format: lowercase, snake_case. Returned in the submit response as { submissionId, intentId, status } and on poll as the full IntentStatusResponse (see below). Poll GET /api/v1/intents/{submissionId} to follow transitions.

Status	Meaning
`accepted`	Gateway has the intent. Signature, expiry, and replay checks passed.
`oracle_pending`	Deposit-shaped intent waiting on Spark operator-DB confirmation for every referenced transfer. Skipped when the intent has no deposits.
`included_pending_finality`	Sequencer included the intent in a block. The EVM transaction has run; finality is pending.
`finalized`	Validators reached quorum on the finality certificate. Settlement has dispatched (or will imminently).
`rejected`	Admission failure, deposit oracle failure, or transaction revert. `statusMessage` carries the reason.
`expired`	The intent’s `expiresAt` passed before any terminal state was reached.

statusMessage for revert cases includes the raw output bytes:

payload_flagged:stage=Execute outcome=Reverted intent_index=0 \
  tx_hash=0x... reason=reverted:gas_used=189179 output=0x1f2a2005

The SDK’s decodeRevertReason() parses this format.

Auth

POST /api/v1/auth/challenge
{ "publicKey": "<33-byte compressed hex>" }

→ { "challenge": "...", "challengeString": "..." }

POST /api/v1/auth/verify
{
  "publicKey": "<33-byte compressed hex>",
  "signature": "<DER-encoded ECDSA hex of SHA-256(challengeString)>"
}

→ { "accessToken": "..." }

Tokens are short-lived. The SDK handles refresh automatically; raw integrations should re-authenticate on 401.

Replay and ordering guarantees

Spark transfer ids can fund at most one finalized intent. Pre-finality, the gateway holds a soft-claim that prevents concurrent submissions but does not survive a rejection.
EVM nonces are standard. The runtime rejects an out-of-order or replayed transaction even if the intent itself reaches the chain twice.
Withdrawal nonces on SparkGateway are monotonic and reconciled on the settlement side, so a finalized withdrawal never settles twice on Spark.

Versioning

The intent canonical-hash version is V2 (currently). Field additions land as new versions; the version is implicit in the absence of an unrecognized field. Treat this surface as semver-stable within a major version of the gateway.

Get started

Integrate Flashnet markets

Build on Execution

Reference

Endpoints

Network info

Submit intent

Look up intent status

Canonical intent message

Status enum

Auth

Replay and ordering guarantees

Versioning

Get started

Integrate Flashnet markets

Build on Execution

Reference

Documentation Index

​Endpoints

​Network info

​Submit intent

​Look up intent status

​Canonical intent message

​Status enum

​Auth

​Replay and ordering guarantees

​Versioning

Endpoints

Network info

Submit intent

Look up intent status

Canonical intent message

Status enum

Auth

Replay and ordering guarantees

Versioning