Skip to main content
POST
Create wallet approval

Authorizations

Authorization
string
header
required

Scoped API key (ttk_...), created in the Totalis app or by a wallet-session user through the API keys routes with a fresh wallet signature; those routes never accept a key. Each key acts for one account, yours or a maker's, and holds only scopes that account can use. Each operation lists the scopes it requires. Send no Origin.

Scopes

funding:deposit
sponsorship:use

Headers

Idempotency-Key
string<uuid>
required

Lowercase UUIDv7 naming this command, unique per caller and route. A retry with the same key and body returns the original result; the same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Body

application/json
value
string<uint256-decimal>
required

Atomic USDC (6 decimals) the approval becomes; 0 revokes it.

Maximum string length: 78
Pattern: ^(0|[1-9][0-9]*)$
nonce
string<uint256-decimal>
required

The permit nonce signed, GET /v1/me/wallet-approval nonce.

Maximum string length: 78
Pattern: ^(0|[1-9][0-9]*)$
deadline
string<uint64-decimal>
required

Unix seconds after which USDC refuses the permit; a permit sent after it ends PERMIT_EXPIRED.

Maximum string length: 20
Pattern: ^(0|[1-9][0-9]{0,18}|1[0-7][0-9]{18}|18[0-3][0-9]{17}|184[0-3][0-9]{16}|1844[0-5][0-9]{15}|18446[0-6][0-9]{14}|184467[0-3][0-9]{13}|1844674[0-3][0-9]{12}|184467440[0-6][0-9]{10}|1844674407[0-2][0-9]{9}|18446744073[0-6][0-9]{8}|1844674407370[0-8][0-9]{6}|18446744073709[0-4][0-9]{5}|184467440737095[0-4][0-9]{4}|18446744073709550[0-9]{3}|18446744073709551[0-5][0-9]{2}|1844674407370955160[0-9]|1844674407370955161[0-5])$
signature
string
required

The account wallet's EIP-712 signature over USDC's EIP-2612 Permit(owner, spender, value, nonce, deadline) in the USDC domain GET /v1/deployment publishes, with the account wallet as owner and GET /v1/me/wallet-approval spender and nonce.

Pattern: ^0x[0-9a-f]{130}$

Response

Admitted, not yet on chain: the permit request as it stands. The approval, or a revoke, takes effect only once its operation is COMMITTED; until then the old approval stands. Follow the operation on the account stream (OPERATION_UPDATED, kind USDC_PERMIT) or resend this request: the same Idempotency-Key and body return the request as it stands before anything else is checked, so save both before the first send. The same permit under another key returns the request it already started.

request_id
string<uuid>
required

The Idempotency-Key that first sent this permit.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
operation_id
string
required

The USDC_PERMIT operation that relays it.

Pattern: ^0x[0-9a-f]{64}$
value
string<uint256-decimal>
required

The approval it sets, atomic USDC; 0 is a revoke.

Maximum string length: 78
Pattern: ^(0|[1-9][0-9]*)$
nonce
string<uint256-decimal>
required

The permit nonce it was signed with.

Maximum string length: 78
Pattern: ^(0|[1-9][0-9]*)$
deadline
string<uint64-decimal>
required

The permit's deadline, Unix seconds.

Maximum string length: 20
Pattern: ^(0|[1-9][0-9]{0,18}|1[0-7][0-9]{18}|18[0-3][0-9]{17}|184[0-3][0-9]{16}|1844[0-5][0-9]{15}|18446[0-6][0-9]{14}|184467[0-3][0-9]{13}|1844674[0-3][0-9]{12}|184467440[0-6][0-9]{10}|1844674407[0-2][0-9]{9}|18446744073[0-6][0-9]{8}|1844674407370[0-8][0-9]{6}|18446744073709[0-4][0-9]{5}|184467440737095[0-4][0-9]{4}|18446744073709550[0-9]{3}|18446744073709551[0-5][0-9]{2}|1844674407370955160[0-9]|1844674407370955161[0-5])$
status
enum<string>
required

Its operation's status. Only COMMITTED set the approval; REVERTED and EXPIRED_UNEXECUTED changed nothing.

Available options:
QUEUED,
IN_FLIGHT,
RETRYABLE,
UNKNOWN,
COMMITTED,
REVERTED,
EXPIRED_UNEXECUTED
transaction_hash
string | null
required

HyperEVM hash of the transaction carrying it; null before it is broadcast.

Pattern: ^0x[0-9a-f]{64}$
failure_reason
enum<string>

Why it changed nothing, present only once status is REVERTED or EXPIRED_UNEXECUTED. PERMIT_EXPIRED: its deadline passed first. PERMIT_NONCE_USED: another permit used its nonce first; read the approval before signing again, as it may already be what you wanted. PERMIT_REVERTED: USDC refused it for another reason.

Available options:
PERMIT_EXPIRED,
PERMIT_NONCE_USED,
PERMIT_REVERTED