List your per-trade BuilderCodes earnings

curl --request GET \
  --url https://staging.apimonaco.xyz/api/v1/buildercodes/payouts \
  --header 'X-Monaco-Signature: <api-key>'

const options = {method: 'GET', headers: {'X-Monaco-Signature': '<api-key>'}};

fetch('https://staging.apimonaco.xyz/api/v1/buildercodes/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.apimonaco.xyz/api/v1/buildercodes/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Monaco-Signature: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.apimonaco.xyz/api/v1/buildercodes/payouts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Monaco-Signature", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://staging.apimonaco.xyz/api/v1/buildercodes/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Monaco-Signature"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "payouts": [
    {
      "tradeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "payoutAddress": "0x0000000000000000000000000000000000000001",
      "token": "0x0000000000000000000000000000000000000002",
      "amount": "1000000",
      "appliedBps": 1000,
      "createdAt": "2023-11-07T05:31:56Z",
      "kind": "REVENUE_SHARE"
    }
  ],
  "total": 123,
  "pageSize": 123,
  "totalPages": 123,
  "nextPageToken": "<string>"
}

GET

api

buildercodes

payouts

List your per-trade BuilderCodes earnings

curl --request GET \
  --url https://staging.apimonaco.xyz/api/v1/buildercodes/payouts \
  --header 'X-Monaco-Signature: <api-key>'

const options = {method: 'GET', headers: {'X-Monaco-Signature': '<api-key>'}};

fetch('https://staging.apimonaco.xyz/api/v1/buildercodes/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.apimonaco.xyz/api/v1/buildercodes/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Monaco-Signature: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.apimonaco.xyz/api/v1/buildercodes/payouts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Monaco-Signature", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://staging.apimonaco.xyz/api/v1/buildercodes/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Monaco-Signature"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "payouts": [
    {
      "tradeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "payoutAddress": "0x0000000000000000000000000000000000000001",
      "token": "0x0000000000000000000000000000000000000002",
      "amount": "1000000",
      "appliedBps": 1000,
      "createdAt": "2023-11-07T05:31:56Z",
      "kind": "REVENUE_SHARE"
    }
  ],
  "total": 123,
  "pageSize": 123,
  "totalPages": 123,
  "nextPageToken": "<string>"
}

Authorizations

X-Monaco-Signature

string

header

required

Ed25519 session-key request signing. Every authenticated request carries three headers: X-Monaco-PublicKey (64-char lowercase-hex session public key), X-Monaco-Timestamp (Unix milliseconds, within 30s of server time), and X-Monaco-Signature (hex ed25519 signature). The signature is over METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body), where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from POST /api/v1/auth/challenge followed by POST /api/v1/auth/verify.

Query Parameters

pageSize

integer<uint32>

default:20

Items per page (max 1000)

Required range: 1 <= x <= 1000

pageToken

string

Pagination cursor with two states:

Omitted or empty string (""): start a cursor walk with no prior position, from the newest credit.
Non-empty: an opaque cursor from a previous response's next_page_token; results resume immediately after that position.

The walk seeks on (created_at, id) descending, served by idx_buildercode_payouts_application_created_id, whose leading key is the caller's own application and whose remaining keys are this seek's, both descending. Both key columns are NOT NULL and fixed for a credit's lifetime. (Spelled without the column list on purpose: the read contract test asserts this request message never mentions a caller-selected identity.)

This REPLACES the removed mode's (sequence, sequence_ordinal, created_at, id) order, whose two leading columns are nullable — no backfill exists for credits written before they did — and a nullable leading key cannot be a total cursor key: the NULL rows sort together at one end, and a seek through them would need a COALESCE no index covers.

ORDERING CHANGE, not just a pagination change. The new key is total and stable — a page can neither skip nor duplicate a credit — but it is NOT chronological inside one persistor batch. created_at defaults to NOW(), which is transaction-start time, so every credit one batch writes shares an identical timestamp; the id tie-break defaults to gen_random_uuid(), which the persistor leaves alone. So within a batch the order is arbitrary and a LATER fill can be listed ahead of an earlier one. The removed order led with sequence and sequence_ordinal precisely because those carry the engine's fill order, and one entry routinely holds several credits (a taker sweeping N makers, or a flattened BatchCreateOrders). Preserving fill chronology would need those columns backfilled first, which is not possible for credits written before they existed. Across batches the order is still newest-first.

total and total_pages are populated and exact, and count the rows the kind filter selects. Filters must match the request that produced the token, or the request is rejected 400.

kind

enum<string>

Only return BuilderCodes payouts of this payout kind: REVENUE_SHARE (the frontend's share of Monaco's fee) or BUILDER_FEE (ordinary builder fees charged to takers and credited to enrolled applications). Omit for every kind.

Available options:

REVENUE_SHARE,

BUILDER_FEE

Minimum string length: 1

Response

payouts

object[] | null

Per-trade credits, newest first.

Show child attributes

total

integer<uint32> | null

Total payout rows for this application.

pageSize

integer<uint32> | null

Items per page.

totalPages

integer<uint32> | null

Total number of pages.

nextPageToken

string | null

Cursor for the next page, minted from the last row of an over-fetched page: this listing is one ordered read, so a page shorter than page_size proves the walk is exhausted and this is empty.

Learn

Build

Libraries

APIs

Resources

List your per-trade BuilderCodes earnings

Authorizations

Query Parameters

Response