Submit a transaction

Submit an already signed transaction for processing. The API does not accept a seed phrase or private key and does not sign transactions on your behalf.

Request body

cURL example

Replace the placeholders with a proposed integration key and a transaction signed by your application. This command documents the contract; the preview endpoint is not a live service.

curl --request POST 'https://api.mokuna.xyz/v1/transactions' \
  --header "Authorization: Bearer $MOKUNA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-example-001' \
  --data '{
    "network": "base",
    "signedTransaction": "SIGNED_TRANSACTION_HEX",
    "clientReference": "order-example-001"
  }'

JavaScript example

Run this pattern on a trusted backend. Supply the signed transaction as an argument; do not put signing secrets in API requests.

async function submitTransaction(signedTransaction, reference) {
  const response = await fetch('https://api.mokuna.xyz/v1/transactions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MOKUNA_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': reference,
    },
    body: JSON.stringify({
      network: 'base',
      signedTransaction,
      clientReference: reference,
    }),
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  return body; // Persist the id before polling for an outcome.
}

202 Accepted

{
  "id": "mtx_example_001",
  "network": "base",
  "status": "received",
  "transactionHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "clientReference": "order-example-001",
  "receivedAt": "2026-09-20T08:00:00Z",
  "requestId": "req_example_001"
}

The hash above is a synthetic example. received acknowledges receipt; follow the returned id through the status endpoint.

Idempotency & retries

The proposed contract retains idempotency keys for 24 hours per API key. Repeating the same key and request body returns the original accepted response; using the same key with a different body returns 409 idempotency_conflict.

After a timeout, retry with the original key and body. This request-level behavior does not replace account nonce management. Coordinate nonce ownership across all routes that can submit the account’s transactions.

Validation failures

Malformed JSON returns 400; a transaction that fails input validation returns 422. No supported network for the integration returns 403. See the error reference for the envelope and retry guidance.