Send Transaction

Most Trustless Work endpoints return an unsigned transaction in XDR format. This endpoint is used to sign such unsigned transactions and send them to the Stellar network.

Use this endpoint after you sign an unsigned XDR returned by another endpoint.

What it does

This endpoint submits a signed Stellar transaction to the network.

Typical flow:

1. Call an endpoint that returns unsignedTransaction.

2. Sign that XDR with the user wallet.

3. Submit the signed XDR here.

Headers

Name	Value
Content-Type	application/json
x-api-key	<token>

API reference

Submit a client-signed XDR to the Stellar network

post

Forwards the signed transaction to Horizon, then polls the Soroban RPC to enrich the response with on-chain metadata. The response has three mutually-exclusive shapes:

• Plain contract call (fund, release, approve, dispute, etc.): { txHash, ledger, code: "STELLAR_TX_SUBMITTED", message }.

• Factory deploy (success): { txHash, ledger, contractId, escrow } with the freshly-indexed snapshot — no code/message.

• Factory deploy (indexer lagging): { txHash, ledger, code: "STELLAR_TX_SUBMITTED_INDEXER_LAGGING", message } — the tx is in the ledger; retry getTransaction(txHash) shortly to recover the contract address.

Clients should branch on code when present, otherwise on the existence of contractId. The code is stable; the message is free text and subject to change.

Authorizations

x-api-keystringRequired

Body

signedXdrstringRequired

Base64-encoded signed Soroban / Stellar XDR. Produced by the client wallet after signing the unsigned XDR returned by an escrow build endpoint.

Example: AAAAAgAAAACkqj...truncated...AAAAAAAAAAAAAAAAAAAA

Responses

200

Transaction accepted by the network. Inspect code (plain or indexer-lagging) or contractId / escrow (factory deploy success) to know which variant you received.

application/json

txHashstringRequired

SHA-256 hash of the submitted transaction (hex).

Example: a3f1c9...0e2

ledgernumberRequired

Ledger sequence number where the transaction was included.

Example: 12345678

contractIdstringOptional

Address of the freshly-deployed escrow contract. Present only when the transaction was a factory deploy and the network confirmed it before the indexer timeout.

Example: CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB

codestring · enumOptional

Stable, machine-readable result code. Present on plain submits and on factory deploys whose Soroban return value did not arrive in time. Absent on successful factory deploys (the caller branches on contractId / escrow instead).

Example: STELLAR_TX_SUBMITTEDPossible values:

messagestringOptional

Human-readable companion to code. Free text — subject to change. Clients that need control-flow decisions must read code, not this.

Example: Transaction submitted to the Stellar network.

400

Request body or query params fail schema validation (wrong type, missing required field, unknown property).

application/json

401

Missing, malformed, expired, revoked or invalid API key.

application/json

403

API key is valid but does not have the role required for this operation.

application/json

422

Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).

application/json

500

Unexpected server-side failure. Use the traceId to look up the incident in server logs or contact support.

application/json

post/stellar/send-transaction

POST /stellar/send-transaction HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "signedXdr": "AAAAAgAAAACkqj...truncated...AAAAAAAAAAAAAAAAAAAA"
}

{
  "txHash": "a3f1c9...0e2",
  "ledger": 12345678,
  "contractId": "CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB",
  "escrow": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "code": "STELLAR_TX_SUBMITTED",
  "message": "Transaction submitted to the Stellar network."
}

Response

This endpoint returns the submitted transaction result from the Stellar network.

Example

send-transaction.ts

import axios from "axios";

const http = axios.create({
  baseURL: "https://dev.api.trustlesswork.com",
  timeout: 10000,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": your_api_key,
  },
});

export const useExample = async () => {
  // Get the signer address
  const { address } = await kit.getAddress();

  const response = await http.post("/any-endpoint", {
    // body requested for the endpoint
  });

  // Get the unsigned transaction XDR
  const { unsignedTransaction } = response.data;

  // Sign the transaction with the wallet
  const { signedTxXdr } = await signTransaction(unsignedTransaction, {
    address,
    networkPassphrase: WalletNetwork.TESTNET,
  });

  // Submit the signed transaction
  const tx = await http.post("/stellar/send-transaction", {
    signedXdr: signedTxXdr,
  });

  return tx.data;
};

Notes

• Pass the signed XDR in the signedXdr field.

• Use the same network passphrase used to build the transaction.

• This step usually comes right after a create, update, fund, or release call.