Create Transaction

curl --request POST \
  --url http://localhost:3000/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromEntityId": "<string>",
  "idempotencyKey": "<string>",
  "asset": "<string>",
  "amount": "<string>",
  "toEntityId": "<string>",
  "toAddress": "<string>",
  "memoTag": "<string>",
  "approvals": [
    "<string>"
  ],
  "reason": "<string>",
  "metadata": {}
}
'

import requests

url = "http://localhost:3000/v1/transactions"

payload = {
    "fromEntityId": "<string>",
    "idempotencyKey": "<string>",
    "asset": "<string>",
    "amount": "<string>",
    "toEntityId": "<string>",
    "toAddress": "<string>",
    "memoTag": "<string>",
    "approvals": ["<string>"],
    "reason": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromEntityId: '<string>',
    idempotencyKey: '<string>',
    asset: '<string>',
    amount: '<string>',
    toEntityId: '<string>',
    toAddress: '<string>',
    memoTag: '<string>',
    approvals: ['<string>'],
    reason: '<string>',
    metadata: {}
  })
};

fetch('http://localhost:3000/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/v1/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromEntityId' => '<string>',
    'idempotencyKey' => '<string>',
    'asset' => '<string>',
    'amount' => '<string>',
    'toEntityId' => '<string>',
    'toAddress' => '<string>',
    'memoTag' => '<string>',
    'approvals' => [
        '<string>'
    ],
    'reason' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "http://localhost:3000/v1/transactions"

	payload := strings.NewReader("{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/v1/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/v1/transactions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

Transactions

Create Transaction

Moves a customer’s balance out — to another customer of yours (toEntityId), or to a blockchain address (toAddress). This is the operation behind the dashboard’s own Transfer and Withdraw actions; a merchant’s own backend key reaches the identical rail.

Both destinations settle the same way: on-chain, through the real withdrawal rail — compliance screening, your withdrawal policy, custody signing, all of it. toEntityId and toAddress differ only in how the receiver is named — an existing customer’s own deposit address, resolved for you, or an address you supply directly — never in what actually happens to the money. There is no ledger-only transfer here: crediting a receiver without a real chain movement behind it would let their balance outgrow what custody actually holds at their address.

If your withdrawal policy requires sign-off at this amount and approvals doesn’t yet meet it, this call refuses outright with 400 APPROVALS_REQUIRED — it does not queue itself for later. Retrying with the same idempotencyKey will not pick up new approvals, even after the threshold is met: the funds this request tried to lock are already unwound under that key, and replaying it returns that same outcome again. Collect every required approval before calling this endpoint, or use a new idempotencyKey once you have them.

The dashboard’s own held-for-approval queue — where an under-approved transfer waits and is completed later once approved — is something the dashboard’s backend layers in front of this same call. Calling this endpoint directly does not get you that queue; it is on you to gather approvals up front.

Requires: ledger:write or transfer:create

POST

transactions

Create Transaction

curl --request POST \
  --url http://localhost:3000/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromEntityId": "<string>",
  "idempotencyKey": "<string>",
  "asset": "<string>",
  "amount": "<string>",
  "toEntityId": "<string>",
  "toAddress": "<string>",
  "memoTag": "<string>",
  "approvals": [
    "<string>"
  ],
  "reason": "<string>",
  "metadata": {}
}
'

import requests

url = "http://localhost:3000/v1/transactions"

payload = {
    "fromEntityId": "<string>",
    "idempotencyKey": "<string>",
    "asset": "<string>",
    "amount": "<string>",
    "toEntityId": "<string>",
    "toAddress": "<string>",
    "memoTag": "<string>",
    "approvals": ["<string>"],
    "reason": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromEntityId: '<string>',
    idempotencyKey: '<string>',
    asset: '<string>',
    amount: '<string>',
    toEntityId: '<string>',
    toAddress: '<string>',
    memoTag: '<string>',
    approvals: ['<string>'],
    reason: '<string>',
    metadata: {}
  })
};

fetch('http://localhost:3000/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "3000",
  CURLOPT_URL => "http://localhost:3000/v1/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromEntityId' => '<string>',
    'idempotencyKey' => '<string>',
    'asset' => '<string>',
    'amount' => '<string>',
    'toEntityId' => '<string>',
    'toAddress' => '<string>',
    'memoTag' => '<string>',
    'approvals' => [
        '<string>'
    ],
    'reason' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "http://localhost:3000/v1/transactions"

	payload := strings.NewReader("{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3000/v1/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3000/v1/transactions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromEntityId\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"toEntityId\": \"<string>\",\n  \"toAddress\": \"<string>\",\n  \"memoTag\": \"<string>\",\n  \"approvals\": [\n    \"<string>\"\n  ],\n  \"reason\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "<string>",
  "details": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

Your API key, kp_test_… or kp_live_….

Body

application/json

fromEntityId

string

required

The customer whose balance this moves out of.

idempotencyKey

string

required

Required string length: 8 - 255

asset

string

required

Chain-qualified asset code, e.g. USDT_TRON.

Pattern: /^[A-Z0-9_]{2,16}$/

amount

string

required

Minor units, as a string — an amount is never a float.

Pattern: /^[1-9][0-9]{0,38}$/

toEntityId

string

Internal: another customer of the same merchant.

toAddress

string

External: a blockchain address. Goes through the withdrawal rail.

Required string length: 16 - 120

memoTag

string

Maximum string length: 64

approvals

string[]

Approver identities, when withdrawal policy requires sign-off.

reason

string

The merchant's own label for this movement — "sell", "buy", "sweep". Recorded for audit; never branched on, so a new product name needs no change here.

Maximum string length: 40

metadata

object