NxTreasury API Documentation
Integrate global settlement infrastructure built for programmable money.
Design Requirement — Not Yet Live
This document is a preview of the upcoming NxTreasury API v1 design. Endpoints described here are currently in development and are subject to change before final release.
Authentication & Security
NxTreasury API protects your funds using enterprise-grade security controls. All endpoints require authentication.
Auth Options
In v1, we provide two equal auth paths. Both are fully supported for all endpoints.
| Method | Use Case | Header |
|---|---|---|
| API Key | Server-to-server integration (scripts, backend workers). Supervisor-approved API keys can access all endpoints, including money-moving requests. | Authorization: Bearer {your_api_key} |
| OAuth 2.0 | Third-party applications acting on behalf of a user. Machine-to-machine client credentials flow (FAPI 2.0 aligned). | Authorization: Bearer <access_token> |
The system is designed to be extensible to future auth mechanisms seamlessly.
FAPI 2.0 Security Profile
Our OAuth implementation is designed to align with the FAPI 2.0 Security Profile for maximum financial security.
- Sender-constrained access tokens via DPoP (Demonstrating Proof-of-Possession) or MTLS
- Strong client authentication (
private_key_jwtor MTLS) - Strict TLS 1.2+ enforcement
- Support for PS256, ES256, and EdDSA JWT signature algorithms
- Authorization Server Metadata and JWKS URI available
Message Signing
For HIGH-RISK approvals (e.g., executing a large transfer request), we employ Message Signing to ensure non-repudiation. A valid cryptographic signature of the request payload must be provided. This is mandatory for high-risk money-moving approvals ONLY and is not required for read-only endpoints or initial request creation.
Idempotency
To safely retry requests without accidentally executing a transfer twice, use the Idempotency-Key header. This is required on all POST endpoints.
curl -X POST https://api.nxtreasury.com/api/v1/transfer_requests \
-H "Authorization: Bearer {api_key}" \
-H "Idempotency-Key: 12345678-abcd-1234-abcd-1234567890ab" \
-d '{"amount": "100", "currency": "USDC", "destination": "0x123..."}'Core Endpoints
Decision Pending (OQ-5)
KYC callout: We are evaluating whether un-KYC'd users can access basic endpoints. Currently, KYC verification may gate functional access.
Exchange client credentials for a short-lived access token (OAuth 2.0 Client Credentials flow). Designed to align with FAPI 2.0 strong client authentication.
Retrieve details of the authenticated identity.
List all wallets within the treasury. Includes wallets endpoint family operations.
curl -X GET https://api.nxtreasury.com/api/v1/wallets \
-H "Authorization: Bearer {access_token}"Retrieve token balances across all wallets. Represents the balances endpoint family.
Initiate a new transfer. High-risk actions require supervisor approval and Message Signing. Belongs to the transfer_requests family.
Create a token swap request on supported dex protocols.
Request cross-chain bridging of assets.
Submit bulk data (CSVs, bulk payments) for asynchronous processing.
Submit multiple sub-operations generated by an AI agent for holistic approval. Belongs to the agent_batch_requests family.
Retrieve historical transactions across the treasury.
Generate financial and compliance reports.
Public keys for JWT verification. This well-known URI is intentionally at the root path per RFC 8414 — not under /api/v1/.
Errors
The API uses standard HTTP status codes. All error responses include a standard JSON error envelope schema.
{
"error": "invalid_request",
"message": "The idempotency key has already been used.",
"code": 409
}Not in v1
The following features are slated for post-v1 releases:
- Internal Admin Surfaces
- Official SDK libraries
- Webhooks (Outbound event notifications)