Reference · Endpoints

Create a programmable endpoint

Mint an endpoint from one of the supported templates; the template decides how it will behave.

POST/v1/programmable-endpoints

Authorization: Bearer ak_test_… · Application API key

Idempotency-Key: <uuid> · required

Try it

This operation writes. Compose it in the playground, where you pick refs from objects you hold and pass one human check before it fires — then follow it back here.

Key capabilities

ProgrammableEndpointCreate

Request body fields

template
owner
valueUnit
thresholdProgram
transientProgram

Refused request fields

The platform derives this material itself; a request that supplies any of it is refused.

providerRefs
collectionRefs
parentEndpointRefs
providerAllocationKeys
locatorPayloads
providerSelectionHints

Contract notes

supportedTemplatescustomer_balance_internal · customer_balance_outbound_internal · customer_balance_collection_child · customer_balance_threshold_internal · customer_balance_transient_collection_child

templateProgramRequirementscustomer_balance_internal:none · customer_balance_outbound_internal:none · customer_balance_collection_child:none · customer_balance_threshold_internal:thresholdProgram · customer_balance_transient_collection_child:transientProgram

thresholdProgramFieldsthresholdMinorUnits · target.kind · target.endpointRef

thresholdTargetKindsendpoint · suspense_endpoint

transientProgramFieldsexpiresAt · drain · returnFallback

transientProgramLabelsdrain:parent_collection_endpoint · returnFallback:quarantine_for_operator_review

Sharp edges

A threshold endpoint requires thresholdProgram at mint, including positive minor units and an endpoint or suspense endpoint target.
A transient collector's program is fixed at mint. There is no edit on this surface — only replacement, which is a workspace act.

Wire receipt

Captured from the real gateway by the scenario suite; nothing here is composed by hand.

Create a programmable endpoint from the customer_balance_internal template; inbound credits target programmable endpoints explicitly.

Request

POST /v1/programmable-endpoints
Authorization: Bearer ak_test_…
Idempotency-Key: 00000000-0000-0000-0000-000000008402
Content-Type: application/json

{
  "template": "customer_balance_internal",
  "owner": {
    "kind": "existing_account_owner",
    "ownerRef": "00000000-0000-0000-0000-000000008401",
    "ownerKind": "business-entity"
  },
  "valueUnit": {
    "kind": "fiat",
    "currency": "NGN"
  }
}

Response · 200

{
  "status": 200,
  "body": {
    "command": {
      "occurrence": "first_accepted",
      "provisioningStatus": "created"
    },
    "endpoint": {
      "value": {
        "template": "customer_balance_internal",
        "accountRef": "f420a7a0-db4c-39e4-b9de-a76aa76a1ea7",
        "endpointRef": "14fd5416-ef87-3487-9132-2c49f5884884",
        "holdingRef": "018f605c-ef4d-31a0-87be-60ac7467610c",
        "ownerRef": "00000000-0000-0000-0000-000000008401",
        "ownerKind": "business-entity",
        "unit": {
          "kind": "fiat",
          "currency": "NGN"
        },
        "ledgerPartition": "customer_liability",
        "ledgerNormalSide": "credit_normal",
        "capabilityPosture": {
          "receive": "internal_only",
          "send": "disabled",
          "lifecycle": "permanent",
          "drain": "no_drain",
          "backing": "internal_ledger",
          "purpose": "customer_balance",
          "gas": "no_gas",
          "liquidity": "no_liquidity"
        },
        "locators": []
      },
      "freshness": "Current",
      "visibility": "Full",
      "evidence": [
        {
          "receiptRef": "e7db02e0-f12d-3015-a2bc-d7fd95d1f905",
          "source": "VaeRuntime"
        },
        {
          "receiptRef": "00000000-0000-0000-0000-0000000000c9",
          "source": "SecurityIdentity"
        },
        {
          "receiptRef": "00000000-0000-0000-0000-0000000000cb",
          "source": "SecurityIdentity"
        }
      ]
    }
  },
  "evidence": [
    {
      "receiptRef": "e7db02e0-f12d-3015-a2bc-d7fd95d1f905"
    },
    {
      "receiptRef": "00000000-0000-0000-0000-0000000000c9"
    },
    {
      "receiptRef": "00000000-0000-0000-0000-0000000000cb"
    },
    {
      "receiptRef": "00000000-0000-0000-0000-000000000154"
    }
  ]
}

captured 2026-07-13 · gateway 0.1.0 · First credit · Create a customer wallet