GET /account/deposit-target
How to fund this account
How to fund this account.
operationId: fetchDepositAddress · CCXT method: fetchDepositAddress
Declared server:
https://api.testnet.nexus.xyz/v1. See Networks.
Authentication: agentAuth, hmacAuth.
Machine-readable funding instructions for the authenticated account, so an autonomous client can fund itself without out-of-band knowledge of how a given deployment accepts collateral.
The response is a discriminated union on mode, and which mode you get is a property of the deployment, not of the request. Branch on mode; do not assume either shape. A deployment with a real deposit-contract address configured answers onchain; otherwise it answers testnet-faucet and points at its synthetic-credit endpoints. There is no request parameter that selects between them.
An address is never fabricated to fill the onchain shape. A deployment configured for on-chain deposits whose address is malformed refuses with 503 rather than silently falling back to the faucet, because depositing to a bad address burns the funds.
confirm is identical in both modes and is the portable primitive: poll GET /account until balance reflects the funds.
This operation is discovery only. It moves no funds, creates no deposit, and has no side effect — acting on the returned faucet or onchain instruction is a separate, explicit step by the caller.
HMAC API key authentication. Send three headers:
X-API-Key: your key ID (e.g.nx_a1b2c3...)X-Timestamp: current time in unix millisecondsX-Signature:hex(hmac_sha256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))
Timestamp must be within 30 seconds of server time.
The key is network-scoped; the signature is not. The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque 401 as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description.
Funding instructions for the authenticated account. Exactly one mode is returned; the fields beyond the common ones depend on it.
Funding instructions for the authenticated account, discriminated on mode. onchain is returned only by a deployment with a real deposit-contract address configured; every other deployment returns testnet-faucet. The mode is a property of the deployment, so a client must branch on it rather than pin one shape.
Authentication failed. All 401 responses return the same opaque body to prevent information leakage. A credential minted on a different network is one of the causes it hides — by design, so that a key id cannot be probed for existence on another network. Do not retry it against another host.
Refused with EARLY_ACCESS_REQUIRED: this deployment restricts funding to early-access participants and the authenticated account is not one. Permanent for that account until it is enrolled — do not retry. The gate deliberately mirrors POST /account/credit and POST /faucet, so an account that cannot be funded is not told how to fund. Deployments with early access disabled never return it. The contract-wide RESTRICTED_JURISDICTION refusal can also surface as a 403 on any operation — see “Jurisdiction restrictions”.
Rate limit exceeded. Retryable — honour retry-after and back off; this is what separates a 429 from the permanent 403 jurisdiction refusals. Branch on the body's code, which is always RATE_LIMIT_EXCEEDED, and on bucket to learn WHICH budget bottlenecked — the buckets are independent, so a caller at its read ceiling can still submit orders and should not back off the whole client. Do not parse message: it is a diagnostic whose wording is not stable. Requests are charged by weight, so exhausting a budget takes fewer heavy calls than x-ratelimit-limit suggests. See “Rate limits” in the API description.
DEPOSIT_TARGET_MISCONFIGURED: the deployment is configured for on-chain deposits but its deposit-contract address is not a well-formed address, so no funding target can be published. This is an operator misconfiguration rather than a transient fault; retrying does not clear it, and the endpoint deliberately refuses rather than answering testnet-faucet, which would mask the bad configuration.
GET /v1/account/deposit-target HTTP/1.1
Host: api.testnet.nexus.xyz
X-API-Key: YOUR_API_KEY
Accept: */*
{
"mode": "testnet-faucet",
"account": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
"asset": "USDX",
"min_amount": "10",
"faucet": {
"primary": {
"method": "POST",
"path": "/account/credit",
"body": {
"amount": "10"
},
"note": "Synthetic test USDX credited off-chain to your exchange balance. Per-API-key allowance (default 500 USDX/day). Omit `amount` to claim the remaining daily allowance."
},
"alternate": {
"method": "POST",
"path": "/faucet",
"note": "Fixed per-wallet test USDX grant (default 10000 USDX), once per 24h per wallet."
},
"disclaimer": "Synthetic test USDX only — no on-chain transfer occurs. The on-chain deposit contract is not yet wired in; this endpoint returns mode=\"onchain\" with a real address once it ships."
},
"confirm": {
"method": "GET",
"path": "/account",
"poll_field": "balance",
"note": "Credit is synchronous (well under the SPEC 30s credit target); poll /account until `balance` reflects the credit before trading."
}
}Test it cannot sign this request. X-Signature is an HMAC computed per call: see Authentication, or use an SDK.
API version 0.9.122
Last updated