TriportRPC
DashboardDocs

POST /v1/referrals/payouts — Request a referral payout

POSThttps://api.triport.io/v1/referrals/payouts

Submits a request to pay out your available referral balance to an on-chain address; the request is created in `requested` status and settled asynchronously by operators.

— (the destination chain is chosen via the network body field)— (any authenticated console session)Console session limits apply

Use this endpoint to cash out your accrued referral earnings. You specify an amount (in micro-units), a destination network, and a payout address. The server checks the request against your available balance — the funds that have unlocked and are not already reserved by a pending payout — and against the minimum payout threshold. If the request passes, a Payout record is created in requested status and returned with 202 Accepted.

Payouts are not settled inline. An operator processes the request out-of-band, moving it through processing → sent (or failed). Poll GET /v1/referrals/payouts to track the lifecycle, or read your current balance from GET /v1/referrals/me.

The amount you can request is bounded server-side by your available balance — the caller cannot exceed it. A request larger than what is available is rejected with balance_insufficient; a request below the minimum is rejected with payout_below_min.

Parameters

This endpoint takes a JSON request body. There are no path or query parameters.

Request bodyobject
amount_microinteger (int64)required
Amount to pay out, in micro-units (1,000,000 micro = 1.00). Must be ≥ the minimum payout and ≤ your available balance.
networkstringrequired
Destination chain for the payout (e.g. solana, ethereum, polygon).
addressstringrequired
Destination wallet address, valid for network. Validated server-side.

Response

202 Accepted with the newly created Payout:

tx_hash, note, and completed_at are omitted until the payout is processed.

idstring (UUID)
Unique payout identifier.
user_idstring (UUID)
The requesting user.
amount_microinteger (int64)
Requested amount, in micro-units.
networkstring
Destination chain.
addressstring
Destination wallet address.
statusstring
Lifecycle status — one of requested, processing, sent, failed, cancelled. New requests start at requested.
tx_hashstring
On-chain transaction hash. Present once the payout has been sent.
notestring
Operator note (e.g. failure reason). Present when set.
requested_atstring (RFC 3339)
When the request was created.
completed_atstring (RFC 3339) | null
When the payout reached a terminal state. Null/omitted while in flight.

Errors

Errors use the shared envelope { "error": "<tag>" }. See errors.md for the full envelope.

CodeError tagWhen it happens
400payout_below_minamount_micro is below the minimum payout threshold.
400payout_address_invalidaddress is not valid for the given network.
400balance_insufficientamount_micro exceeds your available balance.
400invalid_argsA field is missing or malformed (e.g. non-positive amount, empty network).
400invalid_jsonThe request body is not valid JSON or exceeds the 4 KiB limit.
401unauthenticatedNo valid console session on the request.
500internalUnexpected server error.

Examples

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/referrals/payouts", {
  method: "POST",
  credentials: "include", // sends the console session cookie
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    amount_micro: 25_000_000,
    network: "solana",
    address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  }),
});


if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`payout failed: ${error}`);
}


const payout = await res.json();
console.log(payout.id, payout.status); // "...", "requested"

TypeScript SDK (@triport/sdk)

import { TriportClient } from "@triport/sdk";


const client = new TriportClient(); // uses the browser session cookie


const payout = await client.referrals.createPayout({
  amountMicro: 25_000_000,
  network: "solana",
  address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
});


console.log(payout.status); // "requested"

Python (triport-sdk)

from triport import TriportClient


client = TriportClient(session=TRIPORT_SESSION)


payout = client.referrals.create_payout(
    amount_micro=25_000_000,
    network="solana",
    address="9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
)


print(payout.id, payout.status)  # "...", "requested"

Notes

  • Asynchronous settlement. A 202 means the request was accepted, not that funds have moved. Track progress with GET /v1/referrals/payouts.
  • Server-bounded amount. The available balance is computed server-side from your unlocked rewards; you cannot request more than is available. Read it via GET /v1/referrals/me (balance.available_micro).
  • Micro-units. Amounts are integers in micro-units: 25000000 = 25.00.
  • Related: GET /v1/referrals/payouts (list payouts), POST /v1/referrals/spend-on-invoice (apply balance to an invoice instead of cashing out).