API v1

NxTreasury API Documentation

Integrate global settlement infrastructure built for programmable money.

This API is live. Authenticate with OAuth 2.0 client_credentials using client_secret_post at the token endpoint. Access tokens are RS256 JWTs published through JWKS key rotation.

Authentication & Security

NxTreasury API protects your funds using enterprise-grade security controls. Public discovery and token endpoints are unauthenticated; resource endpoints require a bearer API key or OAuth access token.

Auth Options

Auth applicability is endpoint-specific in v1. Use the narrowest credential that matches the operation you need.

Method	Use Case	Header
API Key	Full API v1 access by default, including identity, wallet, balance, transaction, report, KYC, transfer, swap, bridge, treasury, agent-batch, and operation workflows. API keys cannot request OAuth tokens.	`Authorization: Bearer {your_api_key}`
OAuth 2.0 Standard	`client_credentials` for registered OAuth clients. Tokens receive full API v1 access by default and expire after 900 seconds.	`Authorization: Bearer <access_token>`
OAuth 2.0 High-Privilege	`client_credentials` with the same full API v1 privileges by default, including transfer, swap, bridge, operation, treasury, KYC, wallet, and agent-batch flows.	`Authorization: Bearer <access_token>`

Self-service API keys and OAuth clients both default to full API v1 access. The scope field is retained for OAuth compatibility, not endpoint authorization.

FAPI 2.0 Security Profile

Our OAuth implementation aligns with FAPI 2.0 security patterns for high-risk financial APIs. This page does not claim certification.

Short-lived client credentials tokens with full API v1 access by default
client_secret_post authentication for current client_credentials token requests
RS256 access tokens with support for JWKS key rotation
Strict TLS 1.2+ transport expectations
Authorization server metadata and JWKS discovery endpoints are published at root-level well-known URIs
High-risk approvals require confirmation tokens plus ES256 detached JWS signed payload submission

DPoP Integrity

DPoP/private-key client authentication helpers exist for hardened integrations, but the current public token endpoint accepts client_secret_post. Endpoint-specific high-risk write flows rely on confirmation tokens and signed payload checks where documented.

Access tokens are bearer tokens signed as RS256 JWTs.
High-risk approvals use confirmation tokens plus ES256 detached JWS payload signing.
State-changing endpoint requirements are documented per endpoint; do not assume DPoP is required unless the endpoint explicitly says so.

Message Signing

For HIGH-RISK approvals (e.g., executing a transfer request), we employ Message Signing to ensure non-repudiation. A valid cryptographic signature of the request payload must be provided using the signed_payload field in the request body.

The signature must be a compact detached JWS (format: header..signature) using the ES256 algorithm. The public key used for verification must be registered on your client profile and the corresponding kid must be present in the JWS header.

The JWS payload is a canonical request string formatted as follows (joined by newlines):

HTTP_METHOD
REQUEST_PATH
SHA256_BODY_HASH (hex)
IDEMPOTENCY_KEY
CONFIRMATION_TOKEN
IAT_UNIX
JTI_NONCE
CLIENT_ID
USER_ID

The SHA256_BODY_HASH is calculated over the JSON request body excluding the signed_payload field, with keys sorted alphabetically and no extra whitespace.

Webhooks

Real-time event notifications for treasury operations, wallet updates, and credential lifecycle events.

Webhook Signature Verification

To ensure notifications originate from nxtApp, verify the X-Nxt-Signature header. We use HMAC-SHA256 with a pre-shared webhook secret.

Signature input: timestamp + b'.' + delivery_id + b'.' + raw_body
The timestamp and delivery_id are provided in X-Nxt-Timestamp and X-Nxt-Delivery-Id headers respectively.
Webhook secrets are one-time delivery only via the platform UI.

import hmac, hashlib
def verify_signature(secret, timestamp, delivery_id, body, signature):
    signed_payload = f"{timestamp}.{delivery_id}.".encode() + body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Idempotency

To safely retry mutating requests without accidentally creating duplicate work, send Idempotency-Key on every mutating /api/v1 request (POST, PUT, PATCH, DELETE) except POST /api/v1/auth/token. This includes POST /api/v1/kyc_submissions, wallet creation, transfer/swap/bridge create-confirm-cancel routes, treasury import creation, agent batch create/approve/reject routes, and DELETE /api/v1/operations/{id}.

curl -X POST https://www.nxtreasury.com/api/v1/transfer_requests \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: 12345678-abcd-1234-abcd-1234567890ab" \
  -d '{"amount": "100", "currency": "USDC", "recipient_address": "0x123..."}'

Core Endpoints

POST /api/v1/auth/token

Exchange client credentials for a short-lived access token using the OAuth 2.0 client credentials flow at /api/v1/auth/token. The implementation is designed to align with FAPI 2.0 security patterns without claiming certification.

Auth: Public endpoint for registered OAuth clients. API keys cannot request tokens.

Name	Type	Required	Description
`grant_type`	string	Yes	Must be `client_credentials`.
`scope`	string	No	Optional for OAuth compatibility. Self-service OAuth clients receive full API v1 access by default; requested scopes do not narrow endpoint authorization.

{
  "grant_type": "client_credentials",
  "client_id": "partner_app",
  "client_secret": "partner_secret"
}

{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 900,
    "scope": "identity:read wallets:read wallets:write ... operations:write"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/identities/me

Retrieve details of the authenticated identity.

Auth: API Key or OAuth. The identity:read scope label is retained for compatibility.

// No request body.

{
  "success": true,
  "data": {
    "id": 1,
    "email": "partner@example.com",
    "username": "partner",
    "is_admin": false,
    "kyc_id": 42,
    "kyc_user_id": 1,
    "verification_id": "ver_123",
    "kyc_status": "approved",
    "kyc_risk": "low",
    "submitted_date": "2026-04-01T00:00:00Z",
    "completed_date": "2026-04-02T00:00:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/kyc_submissions

List KYC submissions for the authenticated principal.

Auth: API Key or OAuth. The kyc:read scope label is retained for compatibility.

Name	Type	Required	Description
`cursor`	string	No	Pagination cursor from the previous response.
`limit`	integer	No	Maximum submissions to return.

// No request body. Use query parameters only.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "status": "pending",
      "risk": "unknown",
      "submitted_at": "2026-05-05T00:00:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "count": 1
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/kyc_submissions

Submit a new KYC package for review.

Auth: API Key or OAuth. The kyc:write scope label is retained for compatibility. Idempotency-Key is required because mutating /api/v1 routes are globally protected by the shared idempotency middleware.

{
  "verification_id": "kyc_ext_ref_001",
  "status": "pending",
  "risk": "unknown",
  "submitted_at": "2026-05-05T00:00:00Z",
  "details": {}
}

{
  "success": true,
  "data": {
    "id": 1,
    "status": "pending",
    "risk": "unknown",
    "submitted_at": "2026-05-05T00:00:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/wallets

List wallets visible to the authenticated principal.

Auth: API Key or OAuth. The wallets:read scope label is retained for compatibility.

Name	Type	Required	Description
`cursor`	string	No	Pagination cursor from the previous response.
`limit`	integer	No	Maximum wallets to return.

// No request body. Use query parameters only.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "email": "partner@example.com",
      "is_authorized": true,
      "public_key": "0x1111111111111111111111111111111111111111",
      "tron_public_key": "TWallet1111111111111111111111",
      "solana_public_key": "So11111111111111111111111111111111111111112"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "count": 1
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/wallets

Create a new treasury wallet on a supported chain.

Auth: API Key or OAuth. The wallets:write scope label is retained for compatibility. Idempotency-Key required.

{
  "chain": "eth"
}

{
  "success": true,
  "data": {
    "wallet_id": 2,
    "chain": "eth",
    "address": "0x...",
    "status": "created",
    "created_at": "2026-05-05T00:00:00Z",
    "updated_at": "2026-01-10T09:00:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/balances

Retrieve balances across wallets visible to the authenticated principal.

Auth: API Key or OAuth. The balances:read scope label is retained for compatibility.

// No request body.

{
  "success": true,
  "data": {
    "balances": {
      "eth": {
        "usdt": 5.0,
        "total_usd": 5.0
      }
    },
    "total_usd": 5.0,
    "stablecoin_total_usd": 5.0,
    "chain_filter": "all",
    "enabled_chains": ["eth"]
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/transfer_requests

Initiate a new transfer request. High-risk actions require confirmation before settlement starts.

Auth: API Key or OAuth. The transfers:write scope label is retained for compatibility. Idempotency-Key is required on create, confirm, and cancel.

{
  "amount": "100.00",
  "currency": "USDC",
  "chain": "eth",
  "recipient_address": "0xRecipientAddress"
}

{
  "success": true,
  "data": {
    "operation_id": "op_...",
    "status": "pending",
    "status_url": "/api/v1/operations/op_...",
    "resource_type": "transfer",
    "resource_id": "tr_...",
    "submitted_at": "2026-01-15T10:30:00Z",
    "confirmation_token": "ctok_...",
    "confirmation_expires_at": "2026-01-15T11:30:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/transfer_requests/{id}/confirm

Confirm a pending transfer request after collecting the returned confirmation token.

Auth: API Key or OAuth. The transfers:write scope label is retained for compatibility. Idempotency-Key is required on create, confirm, and cancel.

Name	Type	Required	Description
`id`	string	Yes	Transfer request identifier to confirm.

{
  "confirmation_token": "ct_...",
  "signed_payload": "header..signature"
}

{
  "success": true,
  "data": {
    "transfer": {
        "transfer_id": "tr_...",
        "amount": "100.00",
        "currency": "USDC",
        "chain": "eth",
        "recipient_address": "0x...",
        "status": "submitted",
        "created_at": "2026-05-05T00:00:00Z",
        "expires_at": "2026-05-06T00:00:00Z"
      },
    "operation": {
      "operation_id": "op_...",
      "status": "processing",
      "status_url": "/api/v1/operations/op_...",
      "resource_type": "transfer",
        "resource_id": "tr_...",
      "submitted_at": "2026-05-05T00:00:00Z",
      "expires_at": "2026-05-06T00:00:00Z",
      "result": null,
      "error": null
    }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/swap_requests

Create a token swap request on supported dex protocols.

Auth: API Key or OAuth. The swaps:write scope label is retained for compatibility. Idempotency-Key is required on create, confirm, and cancel.

{
  "token_in": "USDC",
  "token_out": "WETH",
  "amount_in": "100.00",
  "chain": "base"
}

{
  "success": true,
  "data": {
    "operation_id": "op_...",
    "status": "pending",
    "status_url": "/api/v1/operations/op_...",
    "resource_type": "swap",
    "resource_id": "swap_...",
    "submitted_at": "2026-05-05T00:00:00Z",
    "confirmation_token": "ct_...",
    "confirmation_expires_at": "2026-05-05T00:15:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/bridge_requests

Initiate a new cross-chain bridge request. High-risk actions require confirmation before settlement starts.

Auth: API Key or OAuth. The bridges:write scope label is retained for compatibility. Idempotency-Key is required on create, confirm, and cancel.

{
  "amount": "100.00",
  "currency": "USDC",
  "source_chain": "eth",
  "destination_chain": "base",
  "destination_address": "0xRecipientAddress"
}

{
  "success": true,
  "data": {
    "operation_id": "op_...",
    "status": "pending",
    "status_url": "/api/v1/operations/op_...",
    "resource_type": "bridge",
    "resource_id": "br_...",
    "submitted_at": "2026-05-05T00:00:00Z",
    "confirmation_token": "ctok_...",
    "confirmation_expires_at": "2026-05-05T00:15:00Z"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/bridge_requests/{id}/confirm

Confirm a pending bridge request. This dispatches async execution of the bridge transaction across the source and destination chains. Confirmation returns 202 Accepted, and the operation status transitions to processing.

Auth: API Key or OAuth. The bridges:write scope label is retained for compatibility. Idempotency-Key, confirmation_token, and signed_payload are required.

{
  "confirmation_token": "ct_...",
  "signed_payload": "header..signature"
}

{
  "success": true,
  "data": {
    "bridge": {
      "id": "br_...",
      "status": "processing"
    },
    "operation": {
      "operation_id": "op_...",
      "status": "processing",
      "status_url": "/api/v1/operations/op_..."
    }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/treasury_import_jobs

Submit bulk data (CSVs, bulk payments) for asynchronous processing.

Auth: API Key or OAuth. The treasury:write scope label is retained for compatibility. Idempotency-Key required.

{
  "source_file_name": "payments.csv",
  "content_base64": "...base64..."
}

{
  "success": true,
  "data": {
    "operation_id": "op_...",
    "status": "pending",
    "status_url": "/api/v1/operations/op_...",
    "resource_type": "treasury_import_job",
    "resource_id": "tij_...",
    "submitted_at": "2026-05-05T00:00:00Z",
    "expires_at": "2026-05-06T00:00:00Z",
    "result": null,
    "error": null
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

POST /api/v1/agent_batch_requests

Submit multiple sub-operations generated by an AI agent for holistic approval. Belongs to the agent_batch_requests family.

Auth: API Key or OAuth. The agent_batches:write and agent_batches:approve scope labels are retained for compatibility. Approve and reject flows also require confirmation_token and signed_payload. Idempotency-Key is required on create, approve, and reject.

{
  "treasury_import_job_id": "tij_01HXXXXXXXXXXXXXXXXXXXXXXX"
}

{
  "success": true,
  "data": {
    "confirmation_token": "ct_...",
    "operation_id": "op_...",
    "status": "pending",
    "status_url": "/api/v1/operations/op_...",
    "resource_type": "agent_batch_request",
    "resource_id": "abr_...",
    "submitted_at": "2026-05-05T00:00:00Z",
    "expires_at": "2026-05-06T00:00:00Z",
    "result": null,
    "error": null
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/transactions

Retrieve historical transactions across the treasury.

Auth: API Key or OAuth. The transactions:read scope label is retained for compatibility.

Name	Type	Required	Description
`cursor`	string	No	Pagination cursor from the previous response.
`limit`	integer	No	Maximum transactions to return.
`chain`	string	No	Restrict results to a blockchain family.
`status`	string	No	Filter by transaction status.

// No request body. Use query parameters only.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "counterparty": "Vendor A",
      "amount": "100.00",
      "currency": "USDC",
      "chain": "eth",
      "due_date": "2026-05-05",
      "status": "approved",
      "origin": "manual",
      "source_file": null,
      "flag_reason": null,
      "tx_hash": null,
      "executed_at": null,
      "created_at": "2026-05-05T00:00:00Z",
      "updated_at": "2026-05-05T01:00:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "count": 1
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/reports

List available financial and compliance report descriptors.

Auth: API Key or OAuth. The reports:read scope label is retained for compatibility.

// No request body.

{
  "success": true,
  "data": [
    {
      "slug": "transactions",
      "name": "Transactions",
      "description": "Review transaction history with optional chain and token filters.",
      "endpoint_hint": "/financial-dashboard/transactions"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "count": 3
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

GET /api/v1/operations

List operations created by prior asynchronous or confirmation-based API calls.

Auth: API Key or OAuth. The operations:read scope label is retained for compatibility.

// No request body. Use optional cursor and limit query parameters.

GET /api/v1/operations/{id}

Poll the status of a long-running API operation returned from an asynchronous create or confirm flow.

Auth: API Key or OAuth. The operations:read scope label is retained for compatibility.

Name	Type	Required	Description
`id`	string	Yes	Operation identifier returned by a previous `202 Accepted` response.

// No request body.

{
  "success": true,
  "data": {
    "operation_id": "op_...",
    "status": "completed",
    "status_url": "/api/v1/operations/op_...",
      "resource_type": "transfer",
    "resource_id": "tr_...",
    "submitted_at": "2026-05-05T00:00:00Z",
    "expires_at": "2026-05-06T00:00:00Z",
    "result": null,
    "error": null
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-05T00:00:10Z"
  }
}

DELETE /api/v1/operations/{id}

Cancel a pending operation before execution continues.

Auth: API Key or OAuth. The operations:write scope label is retained for compatibility. Idempotency-Key is required and this route does not accept a request body.

GET /.well-known/oauth-authorization-server

Authorization server metadata published at the RFC well-known path. This endpoint returns raw RFC JSON and is not wrapped in the platform envelope.

GET /.well-known/jwks.json

Public keys for RS256 JWT access-token verification. This well-known URI is intentionally at the root path per RFC 8414 and RFC 7517 — not under /api/v1/. ES256 is used for detached signed payloads where required, not for access tokens.

Errors

The API uses standard HTTP status codes. All error responses include a standard JSON error envelope schema.

{
  "success": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key has already been used with a different request body.",
    "details": {}
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6g7h8i9j0",
    "timestamp": "2026-05-05T00:00:00Z"
  }
}

Not in v1

The following features are slated for post-v1 releases:

Internal Admin Surfaces
Advanced controls: MTLS, PAR, and JAR (currently N/A to client-credentials flow)

Ready to Build?

Generate full-access API keys from your account, or request enterprise OAuth access for token-based workflows.

Generate API Keys